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Chapter 1. About This Book 


This book describes the OODialog framework, which is implemented as an external library package, and 
part of the Open Object Rexx distribution on the Windows® platform. It describes the classes in the 
framework and how to use the framework to program user interfaces. 


1.1. Who Should Use This Book 


This book is intended for Object Rexx programmers who want to design graphical user interfaces for 
their applications. 


1.2. How This Book is Structured 


This document should be divided into two parts - a tutorial and a reference. In the original 
documentation accompanying IBM’s Object Rexx, the documentation was in two parts. Unfortunately, 
the tutorial portion mostly described how to use the IBM Resource Workshop. The Resource Workshop 
has not been contributed to the open source community and is therefore not a part of the Open Object 
Rexx project. Because the tutorial section was primarily directed towards using the Resource Workshop, 
it does not make much sense in the current context. 


This book is primarily a reference that describes the classes and methods in detail. There is no tutorial. 
The tutorial portion needs to be written (or re-written depending on your point of view.) 


Note: There is no loss of functionality in ooDialog because of the absence of the Resource 
Workshop. The Windows resource format is well understood and there are any number of free or 
inexpensive resource editors that do a better job of designing dialogs than the Resource Workshop 
did. (The Resource Workshop was a 16-bit application with limited capacity for the newer features in 
the Windows user interface.) ooDialog works fine with dialogs designed by any modern resource 
editor. 


1.3. Related Information 


Open Object Rexx: Programming Guide 
Open Object Rexx: Reference 


1.4. How to Read the Syntax Diagrams 


Throughout this book, syntax is described using the structure defined below. 


* Read the syntax diagrams from left to right, from top to bottom, following the path of the line. 
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The >>--- symbol indicates the beginning of a statement. 

The ---> symbol indicates that the statement syntax is continued on the next line. 
The >--- symbol indicates that a statement is continued from the previous line. 
The --->< symbol indicates the end of a statement. 


Diagrams of syntactical units other than complete statements start with the >--- symbol and end with 
the ---> symbol. 


* Required items appear on the horizontal line (the main path). 


»»-STATEMENT--required item------------------------------------ >< 


* Optional items appear below the main path. 


»»-STATEMENT--4--------------- фантаст >< 
+-optional_item-+ 


* If you can choose from two or more items, they appear vertically, in a stack. 


If you must choose one of the items, one item of the stack appears on the main path. 


»»-STATEMENT---4-required choicei-4----------------------------- >< 
+-required_choice2-+ 


* If choosing one of the items is optional, the entire stack appears below the main path. 


»»-STATEMENT--4------------------ 4----------------------------- >< 
+-optional_choice1-+ 
+-optional_choice2-+ 


* If one of the items is the default, it appears above the main path and the remaining choices are shown 
below. 


+-default_choice--+ 
>>-STATEMENT--+----------------- a a ea a шырыш ышы emt >< 

+-optional_choice-+ 

+-optional_choice-+ 


* An arrow returning to the left above the main line indicates an item that can be repeated. 


»»-STATEMENT----repeatable item-*------------------------------ >< 


A repeat arrow above a stack indicates that you can repeat the items in the stack. 


* A set of vertical bars around an item indicates that the item is a fragment, a part of the syntax diagram 
that appears in greater detail below the main diagram. 


>>-STATEMENT--| fragment |------------------------------------- >< 
fragment: 


|--expansion_provides_greater_detail---------------------------- 
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* Keywords appear in uppercase (for example, PARM1). They must be spelled exactly as shown but you 
can type them in upper, lower, or mixed case. Variables appear in all lowercase letters (for example, 
parmx). They represent user-supplied names or values. 


* If punctuation marks, parentheses, arithmetic operators, or such symbols are shown, you must enter 
them as part of the syntax. 


The following example shows how the syntax is described: 


V | 
»»-MAX(----number-4--)----------------------------------------- >< 


1.5. Getting Help 


The Open Object Rexx Project has a number of methods to obtain help for ooRexx. These methods, in 
no particular order of preference, are listed below. 


1.5.1. The Rexx Language Association Mailing List 


The Rexx Language Association (http://www.rexxla.org/) maintains a mailing list for its members. This 
mailing list is only available to RexxLA members thus you will need to join RexxLA in order to get on 
the list. The dues for RexxLA membership are small and are charged on a yearly basis. For details on 
joining RexxLA please refer to the RexxLA Home Page (http://rexxla.org/) or the RexxLA Membership 
Application (http://www.rexxla.org/rexxla/join.html) page. 


1.5.2. The Open Object Rexx SourceForge Site 


The Open Object Rexx Project (http://www.oorexx.org/) utilizes SourceForge (http://sourceforge.net/) to 
house the ooRexx Project (http://sourceforge.net/projects/oorexx) source repositories, mailing lists and 
other project features. Here is a list of some of the most useful facilities. 


The ooRexx Forums 


The ooRexx project maintains a set of forums that anyone may contribute to or monitor. They are 
located on the ooRexx Forums (http://sourceforge.net/forum/?group_id=119701) page. There are 
currently three forums available: Help, Developers and Open Discussion. In addition, you can 
monitor the forums via email. 


The Developer Mailing List 


You can subscribe to the oorexx-devel mailing list at ooRexx Mailing List Subscriptions 
(http://sourceforge.net/mail/?group_id=119701) page. This list is for discussing ooRexx project 
development activities and future interpreter enhancements. It also supports a historical archive of 
past messages. 
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The Users Mailing List 


You can subscribe to the oorexx-users mailing list at ooRexx Mailing List Subscriptions 
(http://sourceforge.net/mail/?group_id=119701) page. This list is for discussing using ooRexx. It 
also supports a historical archive of past messages. 


The Announcements Mailing List 


You can subscribe to the oorexx-announce mailing list at ooRexx Mailing List Subscriptions 
(http://sourceforge.net/mail/?group_id=119701) page. This list is only used to announce significant 
ooRexx project events. 


The Bug Mailing List 


You can subscribe to the oorexx-bugs mailing list at ooRexx Mailing List Subscriptions 
(http://sourceforge.net/mail/?group_id=119701) page. This list is only used for monitoring changes 
to the ooRexx bug tracking system. 


Bug Reports 


You can create a bug report at ooRexx Bug Report 
(http://sourceforge.net/tracker/?group_id=119701&atid=684730) page. Please try to provide as 
much information in the bug report as possible so that the developers can determine the problem as 
quickly as possible. Sample programs that can reproduce your problem will make it easier to debug 
reported problems. 


Request For Enhancement 
You can suggest ooRexx features at the ooRexx Feature Requests 
(http://sourceforge.net/tracker/?group id-119701&atid2684733) page. 
Patch Reports 


If you create an enhancement patch for ooRexx please post the patch using the ooRexx Patch Report 
(http://sourceforge.net/tracker/?group id-119701&atid-684732) page. Please provide as much 
information in the patch report as possible so that the developers can evaluate the enhancement as 
quickly as possible. 


Please do not post bug patches here, instead you should open a bug report and attach the patch to it. 


1.5.3. comp.lang.rexx Newsgroup 


The comp.lang.rexx (news:comp.lang.rexx) newsgroup is a good place to obtain help from many 
individuals within the Rexx community. You can obtain help on Open Object Rexx or on any number of 
other Rexx interpreters and tools. 
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ooDialog is a framework that aids ooRexx programmers in adding graphical elements to their Rexx 
progamms. The framework provides the base infrastructure, through a number of classes, that the 
programmer builds on to quickly produce Windows dialogs. This book is a reference to the ooDialog 
classes, methods, and utilities that make up the base infrastructure. 


2.1. Gettting Started 


Unfortunately, there is little documentation for the newcomer on how to get started using ooDialog. Until 
that type of documentation can be written, the sample ooDialog programs that accompany the ooRexx 
distribution are probably the best source of help in getting started. However, there are also numerous 
snippets of example code in this book. 


2.2. OODialog Class Reference 


The classes provided by OODialog form a hierarchy as shown in The Hierarchy of OODialog Classes. 
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Figure 2-1. The Hierarchy of OODialog Classes 
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PlainBaseDialog, BaseDialog 
Base methods regardless of whether the dialog is implemented as a binary resource, a script, or 
dynamically. PlainBaseDialog provides limited functionality. 

PlainUserDialog 
Subclass of PlainBaseDialog used to create a dialog with all its control elements or to execute a 
dialog stored in a resource script (.RC). This class has limited functionality. 

DynamicDialog, DialogExtensions, WindowBase, WindowExtensions 
Internal mixin classes used to extend PlainBaseDialog, PlainUserDialog, BaseDialog, UserDialog, 
and DialogControl. The methods provided by these classes are not listed separately but are listed in 
BaseDialog or UserDialog. 

UserDialog 
Subclass of BaseDialog used to create a dialog with all its control elements, such as push buttons, 
check boxes, radio buttons, entry lines, and list boxes. 

ResDialog 
Subclass of BaseDialog for dialogs within a binary (compiled) resource file (DLL). 


CategoryDialog 
Subclass of UserDialog used to create a dialog with several pages that overlay each other. 


TimedMessage 


Class to show a message window for a defined duration. 


InputBox 


Class to dynamically define a dialog with a message, one entry line, and two push buttons (OK, 
Cancel). 


PasswordBox 


Similar to InputBox, but keystrokes in the entry line are shown as asterisks (*). 


IntegerBox 


Similar to InputBox, but only numeric data can be entered in the entry line. 


MultiInputBox 


Similar to InputBox, but with multiple entry lines. 


ListChoice 


Class to dynamically define a dialog with a list box, where one line can be selected and returned to 
the caller. 


MultiListChoice 


Similar to ListChoice, but more than one line can be selected and returned to the caller. 
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CheckList 


Class to dynamically define a dialog with a group of check boxes, which can be selected and 
returned to the caller. 


SingleSelection 


Class to dynamically define a dialog with a group of radio buttons, where one can be selected and 
returned. 


Dialog 


Subclass of UserDialog for simple dialogs. You can change the default dialog style from 
UserDialog to ResDialog. 


AnimatedButton 


Class to implement an animated button within a dialog. 


DialogControl 


Class to implement methods that are common to all dialogs and dialog controls. 


TreeControl 


Class to implement a tree to display the list of items in a dialog in a hierarchy. 


ListControl 


Class to implement a list view to display the items in a dialog as a collection. 


ProgressBar 


Class to implement a progress indicator within a dialog. 


SliderControl 


Class to implement a slider or trackbar within a dialog. 


TabControl 


Class to implement tabs, which can be compared to dividers in a notebook or labels in a file cabinet. 


StaticControl 


Class to query and modify static controls, such as static text, group boxes, and frames. 


EditControl 


Class to query and modify edit controls, which are also called entry lines. 


ButtonControl 


Class to implement push buttons within a dialog. 


RadioButtonControl 


Class to implement radio buttons within a dialog. 


8 ooRexx OODialog Reference Version 4.0.0 


Chapter 2. Brief Overview 


CheckBoxControl 


Class to implement check boxes within a dialog. 


ListBoxControl 


Class to implement list boxes within a dialog. 


ComboBoxControl 


Class to implement a combo box, which combines a list box with an edit control. 


ScrollBarControl 


Class to implement a scroll bar within a dialog. 


PropertySheetControl 


Class to implement a property sheet, which is similar to a category dialog that spreads its dialog 
items over several pages (categories), where the individual pages are controlled by a tab control 
instead of radio buttons or combo box lists. 


2.3. Definition of Terms 


resource id 


The identification number of a dialog resource. There are several different types of dialog resources, 
menus, dialog controls, and bitmaps, to name a few. You assign IDs when you create the resource 
definition for your dialog. An ID can be either numerical (for example, 1) or symbolic (for example, 
"IDOK"). 


IDs must be unique for each resource of the same type. Although two resources of different types 
may have the same ID, when using symbolic IDs with ooDialog, it is advisable to give all resources 
unique numerical IDs. 


symbolic id 


Defining a symbolic name for each numeric resource ID is often useful in programs that work with 
resource IDs. The symbolic name is then used where ever a numeric resource ID is needed. 
Symbolic names are easier to remember than numeric IDs and can make the code easier to 
understand. 


The mechanism ooDialog provides for using symbolic IDs is the ConstDir attribute of the dialog 
classes. This is a directory object where the indexes are symbolic IDs and the item at each index is 
the numerical value of the ID. 


Some generic resources are bound to the oodialog.dll. They can be used in any ooDialog program 
and are accessed using the .ResourceImage class. Programmers should always use their symbolic 
ID rather than their numeric ID in case the numeric value changes in future versions. To allow for 
future expansion, the ooDialog programmer should consider the resource IDs of 1 through 50 as 
reserved for ooDialog. Programmers can avoid conflicts by using IDs greater than 50 for resource 
IDs they assign in their programs. 
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The symbolic IDs in the following table are pre-defined by ooDialog and placed in the ConstDir 
when an instance of a dialog class is created. All symbolic names after IDC_STATIC in the table 
refer to resources bound to oodialog.dll for general use by the ooDialog programmer. 


Table 2-1. Symbolic IDs Used by ooDialog 









































Numeric ID or Symbol Symbolic ID ResourceType 
1 IDOK Button Control 

2 IDCANCEL Button Control 

9 IDHELP Button Control 
-1 IDC_STATIC Static Control 
ШІ DLG. OODIALOG IDI DLG OODIALOG Icon 

ІШІ DLG. APPICON ШІ DLG. APPICON Icon 

IDI DLG. APPICON2 IDI_DLG_APPICON2 Icon 

ШІ DLG_OOREXX IDI_DLG_OOREXX Icon 

IDI DLG. DEFAULT ШІ DLG. DEFAULT Icon 





#define statement 


Define statements are often used in the C and С++ languages to define symbolic names for 
numerical values. Because of this, it is common in Windows programs with dialogs to define 
symbolic names for resource IDs. Most Windows resource editors use symbolic IDs, (some to a 
limited degree, others exclusively.) Often the define statements are put in a header file so they are 
available both to the resource compiler and to the program code. The defines take the form of: 
#define symbolicName numericValue as in this example: 


511 


#define ID_PUSHBUTTON1 413 
#define ID_EDIT1 
#define ID_LISTBOX1 


602 





When ooDialog parses a resource script or a header file and finds a define statement, it will add the 
symbolic ID to the ConstDir directory object of the dialog. Resource scripts are used by subclasses 
of the UserDialog (see the Load method.) All the ooDialog dialog classes accept a header file as an 
optional parameter when a new instance of a dialog object is created. (See for example the Init 
method in the BaseDialog or UserDialog sections.) Symbolic IDs added to the ConstDir can be 
used in any method of the ooDialog classes where a resource ID is needed. 


header file 


A common practice when programming applications in Windows that use dialogs and dialog 
resources is to place symbolic defines in a separate file. These files often have a .h extension and are 
usually called header files. Windows resource editors often manage a header file for the symbolic 
IDs automatically. (For instance Microsoft’s dialog editor creates, writes, and reads the resource ID 
header file completely on its own. The user does not need to take any action other than including the 
file in her program.) 


handle 


A unique reference to a Windows object assigned by the system. It can be a reference to a dialog, a 
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particular dialog item, or a graphic object (pen, brush, font). Handles are required for certain 
methods; they can be retrieved from the system when needed. 


dialog icon 


The term dialog icon is used in this documentation to refer to the icon that is displayed in the left 
hand corner of the title bar of a dialog. In Windows this is often called the application icon. The 
dialog icon is also used for the Task Bar display and in the AltTab task switcher application. 


The dialog icon for a specific dialog can be set when the dialog is run using one of the execute 
methods. See the Execute or Popup methods for example. ooDialog provides four pre-defined icons 
for use in dialogs. Custom icons can be used by including the icon in a binary (compiled) resource, 
a resource script, or by using Ше addIcon method of the UserDialog. The following table shows the 
symbolic IDs of the pre-defined icons. The symbolic ID should always be used in case the numeric 
value is changed in the future. In addition, the programmer should avoid using numeric IDs 
reserved by ooDialog. The ІІ DLG_DEFAULT is a fifth symbolic ID that represents the default 
dialog icon. This ID can always be used where a dialog icon ID is needed. 


Table 2-2. ooDialog Supplied Icons 


























Description Symbolic ID 

The default, the letters OOD IDI_DLG_OODIALOG 
Dialog box image IDI DLG. APPICON 
Fancier dialog box image ШІ DLG. APPICON2 
The ooRexx image ШІ рс OOREXX 
IDI DLG. DEFAULT IDI DLG. DEFAULT 








device context 


Stores information about the graphic objects that are displayed, such as bitmaps, lines, and pixels, 
and the tools used to display them, such as pens, brushes, and fonts. А device context can be 
acquired for a dialog or a button; it must be explicitly freed when the text or graphic operations are 
completed. 


Common Controls Library (ComCt132) 


The dialog control windows used in dialogs, List- Views, Edit, Tree- Views, etc., are supplied by 
Microsoft in the common controls library. This is a DLL with the name comctl32.dll. Every version 
of Windows is supplied with a common controls library. However, Microsoft has updated the library 
a number of times to provide enhanced functionality and improved features 


Each new version of the library is backwards compatible with previous versions, but will contain 
features not available in older versions. For instance, some of the List-View extended styles are 
only available with a 6.0, or later, version of the common controls library. ooDialog can only 
provide the features available in the version of the common controls libray on the system ooDialog 
is running on. 


Therefore, an ooDialog program running on a Windows 2000 machine will not have available some 
of the features that are available when ooDialog is running on a XP service pack two system. The 
DIgUtil class provides a method, comCtl32 Version that allows the programmer to determine the 
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exact version of the common controls library that ooDialog is using. In the documentation for the 
ooDialog dialog control classes, features that are not available in all versions of the common control 
library are noted. The minimum version of the library that is needed is listed. In general, at this 
time, all features of ooDialog are avaialable on Windows XP or later. This may change in the future 
as Vista has common control features not available on XP. 


pixel 


Individual addressable point within a window. VGA screens support 640 by 480 pixels, SVGA 
screens support higher resolutions, such as 800 by 600, 1024 by 768, 1280 by 1024, and 1600 by 
1200. Pixel values in a dialog start at the top left corner and include the window title and border. 


dialog unit 


Dialog box templates contain measurements that define the size and position of the dialog box and 
its controls. These measurements are device independent. This allows a single template to be used 
to create the same dialog box for all types of display devices. Using device independent 
measurements allows a dialog box to have the same proportions and appearance on all screens 
despite differing resolutions and aspect ratios between screens. 


These measurements are called dialog template units, often shortened to just dialog units in this 
documentation. 


The following paragraph in italics, which has been the sole documentation of dialog units in the 
ooDialog documentation prior to version 4.0.0, is unfortunately incorrect. The value of a dialog unit 
is dependent on the font actually used in the dialog, not on the system font. The statements below 
were probably true in very early versions of Windows when every dialog used system 8 pt font. 
Today it is highly unusual for a dialog to use system 8 pt font. The factorX and factorY values are 
calculated incorrectly. These values are only correct if the dialog is using system 8 pt font and are 
incorrect for a dialog using any other font. 


There is a horizontal and a vertical dialog base unit to convert width and height of dialog boxes and 
controls from dialog units to pixels and vice versa. The value of these base units depend on the 
screen resolution and the active system font; they are stored in attributes of the UserDialog class. 


xPixels = xDialogUnits * self^FactorX 


color 


Each color supported by the Windows operating system is assigned a number. Sample color indexes 
are 0 (black), 1 (dark red), 2 (dark green), 3 (dark yellow), 4 (dark blue), 5 (purple), 6 (blue grey), 7 
(light grey), 8 (pale green), 9 (light blue), 10 (white), 11 (grey), 12 (dark grey), 13 (red), 14 (light 
green), 15 (yellow), 16 (blue), 17 (pink), 18 (turquoise). 


color palette 


An array that contains color values identifying the colors that can currently be displayed or drawn 
on the output device. 


Color palettes are used by devices that can generate many colors but can only display or draw a 
subset of them at a time. For such devices, Windows maintains a system palette to track and manage 
the current colors of the device. 
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Applications do not have direct access to this system palette. Instead, Windows associates a default 
palette with each device context. Applications can use the colors in the default palette. 


The default palette is an array of color values identifying the colors that can be used with a device 
context by default. Windows associates the default palette with a context whenever an application 
creates a context for a device that supports color palettes. The default palette ensures that colors are 
available for use by an application without any further action. The default palette typically has 20 
entries (colors), but the exact number of entries can vary from device to device. The colors in the 
default palette depend on the device. Display devices, for example, often use the 16 standard colors 
of the VGA display and 4 other colors defined by Windows. 


Windows documentation 


The term Windows documentation is used throughout the ooDialog reference to refer to the 
Windows Operating System documentation provided by Microsoft. The documentation is called the 
MSDN Library. The library is provided online for anyone to access. In addition, since May 2006, 
Microsoft has also provided free of charge the ISO images of the library installation program. 
Anyone can download the ISOs, burn them to a CD and install the library locally on their system. 


It is not necessary for the ooDialog programmer to know or understand the underlying Windows 
API that ooDialog is built on. However, as programmers write more sophisticated ooDialog 
applications, it may prove helpful to look up certain details in the MSDN Library. The information 
below is provided to help the ooDialog programmer locate the MSDN Library, if they would like to. 
All things on the Internet change. The URLs listed here are accurate at the time of this writing. 


The online MSDN Library is currently located at: 
http://msdn2.microsoft.com/en-us/library/default.aspx. 

Directions to the downloadable ISO images of the MSDN Library have been posted on this blog 
entry: 

http://blogs.msdn.com/robcaron/archive/2006/07/26/6 788977 .aspx 


A Google search using: "Rob Caron" General Downloads MSDN Library should also turn up the 
blog entry. 


Windows platform SDK 


The Windows Platform SDK is provided free of charge by Microsoft. The SDK is not needed to 
write ooDialog programs. However, combining the use of the documentation in the MSDN Library 
with the SDK allows very sophisticated ooDialog programs to be written. In general, the ooDialog 
framework takes care of the low-level details needed to work with the Windows API. However, 
there are a few generic ooDialog methods that provide direct access to the Windows API. 


As an example, the AddUserMessage method allows the programmer to connect any Windows 
message sent to a dialog to a method in his ooDialog class. To use this method, the programmer 
would go to the MSDN library to look up details on the message and message parameters he is 
interested in. He would then use the Platform SDK to determine the numeric value of the Windows 
message and possibly the numeric values of its parameters. 


This link provides some good information on the Platform SDK in general and also points the 
reader to where to get a SDK. 


http://en.wikipedia.org/wiki/Platform SDK 
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Again, note that it is not at all necessary to obtain, or understand details concerning, the Platform 
SDK. This information is provided for those programmers that have reached the point where they 
think a method like AddUserMessage might help them and need some direction as to how to go 
about using it. 


System error code 


The term system error code refers to an error code set by the Windows operating system when an 
API fails. ooDialog provides an interface to the Windows APIs and when an error is detected many 
of the ooDialog methods have some means of conveying the system error code to the programmer. 
The ooDialog programmer can look up the meaning of a system error code in the MSDN library to 
understand better the cause of a failure. 


Note that not all APIs set the system error code. 


2.4. ooDialog 4.0.0 and the future 


ooDialog is now open source, being developed by committers who volunter their time. It is no longer 
developed by IBM. ooRexx 4.0.0 has introduced a greatly improved native API for extenal packages. 
ooDialog is being converted to use the new API. 


What are the implications of these facts? 


Bug fixes and the addition of new features can only be done at the pace of the committers free time. 


Users of ooDialog can directly influence the future direction of ooDialog through participation in the 
project. Primarily by filing bug reports, opening requests for features, and discussing on the users or 
developers list what they would like to see, or not see. 


The new API will make it easier to add new features that are more robust. This should allow ooDialog 
to add the newer GUI elements of Windows XP and Vista in a reasonable time frame. 


The new API makes some change in behavior of ooDialog methods unavoidable. 


The purpose of this section is to briefly expand upon the implications above and outline the direction 
ooDialog is currently taking. The point of this is to make users aware of what to look for in version 4.0.0 
and to allow them to influence the direction taken, if they choose to. 


New Native API 


ooRexx 4.0.0 introduced a new native API for use in extending the ooRexx interpreter. This API is 
object-orientated and gives external packages more access to features of the interpreter. One 
important aspect of the new API is that not everything passed back and forth between the interpreter 
and the external plackage (the ooDialog framework in this case) needs to be a string. This allows the 
external packages to make better use of object-orientated design. 


АП new function added to ooDialog will use the new API. Existing function will be converted to 
take full advantage of the new API. This conversion has started, but will take place over time. It is 
expected that some of the original design that is not optimal due to the restrictions of the older API 
will be phased out. Alongside of that, some design that, in hindsight, seems incorrect will also be 
phased out. 


14 ooRexx OODialog Reference Version 4.0.0 


Chapter 2. Brief Overview 


New Classes 


In the past, the ooDialog framework made heavy use of two basic objects, a dialog and a dialog 
control. Every method and every functionality was added to a dialog and to a dialog control. This 
had the tendency to produce large monolithic class structures and in many ways negates some of the 
value of using classes. 


In ooDialog 4.0.0 the process of introducing new, smaller, classes to handle related function began. 
In addition, some effort started to factor out of the dialog or dialog control object function or 
behavior that is not really part of a dialog or control object. One example of this is the matter of 
bitmaps, icons, etc.. Bitmaps and icons are images. The data and methods to work with bitmaps or 
other images are better suited to an image object than a dialog object. 


The future evolution of ooDialog will be to add new smaller objects that better model the function 
the programmer needs to produce sophisticated Windows dialogs. These classes may be introduced 
slowly, with just the basic function introduced in one release and the functionality expanded in later 
releases. For instance, in ooDialog 4.0.0 the Rect and Point classes were introduced without a lot of 
functionality. One common behavior of rectangles and points is to ask the rectangle if it contains 
this point. The two classes formed the basis to add that behavior in a later release. 


Objects as Arguments and Return Values 


The 4.0.0 native API makes passing objects as arguments to external packages much easier. And, 
the flip side of this is returning objects from external packages. The older API forced everything to 
be a string. ooDialog will migrate towards using more objects as arguments to, and return values 
from, methods implemented externally. Ultimately, this will make things easier on the programmer, 
allow better access to the underlying capabilities of the operating system, and produce more 
readable code. 


For example, take the task of repositioning a dialog control on a dialog. The operating system 
provides a means to get the current rectangle of any window on the screen, it provides a means to 
map that rectangle on the screen to the client area of any other window, and it provides a means to 
move any window from one position to another. Using the Rect class mentioned above and some 
pseudo code, a future version of ooDialog might handle this task like this: 


rectangle = dlgControl^getWindowRect 
rectangle^mapToClient (dlg) 


-- Shift the control left 10 pixels and up 5 pixels 
rectangle^offset(10, -5) 
dlg^moveControl(dlgControl, rectangle) 


Another example using the Size class: 


size = button^getIdealSize 
button~setSize (size) 


-- The above could also be written: 
button^setSize(button^getlIdealSize) 


Syntax errors 


In the past, ooDialog never raised any error conditions. This, in the author's opionion, lead to a lot 
of user confusion. Things simply did not work and the user had no idea why. Quite often it was 
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merely a matter of using the wrong arguments. Going forward, ooDialog will begin making better 
use of the Rexx facility of raising error conditions when things are not right. 


Part of this will be the direct result of converting to the 4.0.0 API and will be unavoidable. In many 
situations the API automatically raises syntax errors when arguments are not correct. As an 
example, take the createFont() method. One argument to the createFont method is the size of the 
font. In the Windows operating system font sizes are whole numbers. If a programmer passes in, say 
10.89, for a font size, when createFont is converted to use the 4.0.0 API this will raise a syntax error. 


All new methods added to the ooDialog framework will raise syntax errors for incorrect aruguments 
and / or unrecoverable errors. Methods converted to use the 4.0.0 API will always raise syntax 
errors in situations similar to the above. This change will help ooDialog programmers write more 
robust, correct programs. 


Deprecated methods 


Starting in ooDialog 4.0.0, methods began being marked as deprecated in the documentation. The 
documentation for deprecated methods points the programmer to the replacement for the deprecated 
methods. There are a number of reasons for marking methods as deprecated, among which are 
incorrect implementation, duplication, sub-optimal implementation, a desire to move to the cleaner 
4.0.0 АРІ, and a strong desire by the maintainers of ooDialog to remove the excess baggage of the 
past. 


The ooDialog programmer is strongly encouraged to take note of the deprecated methods. To 
definitely not use depracted method in new code, and to migrate deprecated methods in existing 
code to their replacements. 
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PlainBaseDialog is the base class of all dialog classes in the ooDialog framework. It implements 
methods that are common to every dialog. PlainBaseDialog should be considered an abstract class. 
Although, a programmer could instantiate a new PlainBaseDialog object, the class does not implement 
all the methods that are needed to execute a dialog. Therefore, not much can be done with a simple 
PlainBaseDialog object. The ooDialog programmer uses subclasses of PlainBaseDialog to actually 
create and execute a real dialog. 


The PlainBaseDialog inherits from the WindowBase mixin class. The WindowBase mixin class 
implements methods that are common to all windows. Since both dialogs and dialog controls are 
windows, the DialogControl class also inherits from WindowBase. 


The PlainUserDialog class subclasses from PlainBaseDialog class and provides all the methods that 
normally are required to execute a dialog that is either created dynamically or loaded from a resource 
script (.RC). Its purpose is to provide a simpler class that can be used for ordinary user interfaces, like 
the standard dialogs. The ooDialog programmer can subclass from the PlainUserDialog to produce 
straighforward, uncomplicated user interfaces. 


The more advanced dialog classes, ResDialog, RcDialog, UserDialog, subclass the BaseDialog class. 
The BaseDialog class subclasses PlainBaseDialog, and like PlainBaseDialog should be considered an 
abstract class. BaseDialog inherits from the WindowExtensions and DialogExtensions mixin classes. 
These classes implement methods that cover asynchronous dialog execution, scroll bar support, resizing 
and repositioning, bitmaps, graphics (device context related methods), scrolling text, and menus (action 
bars). The ResDialog, RcDialog, UserDialog classes, and their subclasses, allow the programmer to 
produce very sophisticated graphical user interfaces. 


Historically, the reason for providing the simpler PlainUserDialog class was to have a smaller package 
that required less system resources for ordinary user interfaces like the standard dialogs. That reason is 
probably not as valid in modern times as it was when ooDialog was being developed to run on Windows 
3.1. 


3.1. PlainUserDialog Class 


PlainUserDialog is a limited version of the UserDialog class. Use ::requires "OODPLAIN.CLS" in your 
script to get access to the PlainUserDialog class. 


Note: If you use ::requires "OODWIN32.CLS" you do not need to specify the : :requires 
"QODIALOG.CLS" directive because OODIALOG.CLS is included from OODWIN32.CLS. 


Note: If you use ::requires "OODIALOG.CLS" you do not need to specify the : :requires 
"DODPLAIN.CLS" directive because OODPLAIN.CLS is included from OODIALOG.CLS. 
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3.1.1. Attributes 


The following list briefly describes the attributes of the PlainUserDialog. 


Attributes: 


Instances of the PlainUserDialog class have the following attributes: 


AutoDetect 
Automatic data field detection on (=1, default) or off (=0). For the UserDialog subclass the 
default is off and Connect... methods or a resource script are usually used. 
AutomaticMethods 


A queue containing the methods that are started concurrently before the execution of the dialog 


ConstDir 
A directory string storing the numerical values assigned to symbolic IDs (#define-statements in 
the resource script) 

DataConnection 
Protected attribute to store connections between dialog items and the attributes of the dialog 
instance 

DlgHandle 
A handle to the dialog 


Finished 


О if dialog is executing, 1 if terminated with OK, and 2 if canceled 


InitCode 


After the Init method has finished executing the value of the attribtute is 0 if no errors were 
detected during initialization, otherwise its value is non-zero. After instantiating a new dialog 
object, the InitCode attribute should be checked. If its value is not 0 then there was some 
problem initializing the object. The programmer should treat this as an error condition and not 
expect that the underlying Windows dialog can be created successfully. 


After the dialog is finished, the attribute will be 1 if the user terminated the dialog with the Ok 
button. Its value will be 2 if the user canceled the dialog. 


UseStem 


Protected attribute that is true (=1) if a stem variable was passed to init 
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3.1.2. Methods 


The following table lists all the class methods, attributes, and instance methods of the PlainUserDialog 
class with links to the full documentation. The individual methods are documented in BaseDialog Class 
or UserDialog Class. 


Table 3-1. PlainUserDialog Class Methods 





































































































Item... ...description 
Class Method Link 
getFontName (Class method) getFontName 
getFontSize (Class method) getFontSize 
setDefaultFont (Class method) setDefaultFont 
Attributes Link 
fontName (Attribute) fontName 
fontSize (Attribute) fontSize 
Instance Methods Link 
AddAttribute AddAttribute 
addBitmapButton addBitmapButton 
addBlackFrame addBlackFrame 
addBlackRect addBlackRect 
addButton addButton 
addButtonGroup addButtonGroup 
addCheckBox addCheckBox 
addCheckBoxStem addCheckBoxStem 
addCheckGroup addCheckGroup 
addComboBox addComboBox 
AddComboEntry AddComboEntry 
addComboInput addCombolInput 
addEntryLine addEntryLine 
addEtchedFrame addEtchedFrame 
addGrayFrame addGreyFrame 
addGrayRect addGrayRect 
addGroupBox addGroupBox 
addEtchedHorizontal addEtchedHorizontal 
addIcon addIcon 
addInput addInput 
addInputGroup addInputGroup 
addInputStem addInputStem 
addListBox addListBox 
AddListEntry AddListEntry 
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Item... ... description 
AddMenultem AddMenultem 
AddMenuSeparator AddMenuSeparator 
addOkCancelLeftBottom addOkCancelLeftBottom 
addOkCancelLeftTop addOkCancelLeftTop 
addOkCancelRightBottom addOkCancelRightBottom 
addOkCancelRightTop addOkCancelRightTop 
addPasswordLine addPasswordLine 
AddPopupMenu AddPopupMenu 
addRadioButton addRadioButton 
addRadioGroup addRadioGroup 
addRadioStem addRadioStem 
addScrollBar addScrollBar 

addText addText 

addUserMsg addUserMsg 

addEtched Vertical addEtchedVertical 
addWhiteFrame addWhiteFrame 
addWhiteRect add WhiteRect 
AutoDetection AutoDetection 

Cancel Cancel 

Center Center 
ChangeComboEntry ChangeComboEntry 
ChangeListEntry ChangeListEntry 
ClearMessages ClearMessages 
ComboAddDirectory ComboAddDirectory 
ComboDrop ComboDrop 
ConnectButton ConnectButton 
ConnectCheckBox ConnectCheckBox 
connectComboBox connectComboBox 
ConnectControl ConnectControl 
ConnectEntryLine ConnectEntryLine 
ConnectList ConnectList 
ConnectListBox ConnectListBox 
ConnectListLeftDoubleClick ConnectListLeftDoubleClick 
ConnectMultiListBox ConnectMultiListBox 
ConnectRadioButton ConnectRadioButton 
Create Create 

CreateCenter CreateCenter 
CreateMenu CreateMenu 
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Item... ... description 
DefineDialog DefineDialog 
DelInstall Delnstall 
DeleteComboEntry DeleteComboEntry 
DeleteListEntry DeleteListEntry 
Disable Disable 
DisableItem DisableItem 
Enable Enable 
EnableItem EnableItem 
Execute Execute 
FindComboEntry FindComboEntry 
FindListEntry FindListEntry 
FocusItem FocusItem 

Get Get 

GetAttrib GetAttrib 
GetButtonRect GetButtonRect 
GetCheckBox GetCheckBox 
GetComboEntry GetComboEntry 
GetComboltems GetComboltems 
GetComboLine GetComboLine 
GetCurrentComboIndex GetCurrentComboIndex 
GetCurrentListIndex GetCurrentListIndex 
GetData GetData 
GetDataStem GetDataS tem 
GetEntryLine GetEntryLine 
getExStyleRaw getExStyleRaw 
GetID GetID 

GetItem GetItem 
GetListEntry GetListEntry 
GetListItems GetListItems 
GetListLine GetListLine 
GetMultiList GetMultiList 
GetPos GetPos 
GetRadioButton GetRadioButton 
GetSize GetSize 
getStyleRaw getStyleRaw 
getTextSize (deprecated) getTextSize 
getTextSizeDlg getTextSizeDlg 
Get Value GetValue 
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Item... ... description 
HandleMessages HandleMessages 
Help Help 

Hide Hide 

HidelItem HidelItem 
HideWindow Hide Window 

Init Init 
InitAutoDetection InitAutoDetection 
InitDialog InitDialog 
InsertComboEntry InsertComboEntry 
InsertListEntry InsertListEntry 
IsDialogActive IsDialogActive 
ItemTitle ItemTitle 

Leaving Leaving 
ListAddDirectory ListAddDirectory 
ListDrop ListDrop 

Load Load 

LoadFrame LoadFrame 
LoadItems LoadItems 
LoadMenu LoadMenu 

Move Move 
NoAutoDetection NoAutoDetection 
OK OK 

Resize Resize 

Run Run 

SetAttrib SetAttrib 
SetCheckBox SetCheckBox 
SetComboLine SetComboLine 
SetCurrentComboIndex SetCurrentComboIndex 
SetCurrentListIndex SetCurrentListIndex 
SetData SetData 
SetDataStem SetDataStem 
SetEntryLine SetEntryLine 
SetListLine SetListLine 
SetListTabulators SetListTabulators 
SetMenu SetMenu 
SetMultiList SetMultiList 
SetRadioButton SetRadioButton 
SetStaticText SetStaticText 
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Item... ... description 
SetTitle SetTitle 
SetValue SetValue 
SetWindowTitle SetWindowTitle 
Show Show 
ShowItem ShowItem 
ShowWindow ShowWindow 
StartIt StartIt 

Stoplt Stoplt 

Title Title 

Title= Title= 

Update Update 
Validate Validate 





3.2. WindowBase Mixin Class 


WindowBase is a mixin class with methods that are common to all windows. It is inherited by both 


dialog and dialog control classes. 


The instance methods implemented by the WindowBase class are listed here as a cross reference. The 
methods are fully documented in other sections of this book. Each method listed has a link to the full 
documentation for that method and an accurate syntax diagram. 


Both the PlainBaseDialog and the DialogControl classes inherit the WindowBase class. Since the 
PlainBaseDialog is the base class for all dialogs and the DialogControl class is the base class for all 
controls, every dialog object and every dialog control object have the instance methods listed here. 


ca E C - + >< 
>>-- e #9 <<< 9555 >< 
22--petPxotylehad---------———-—-—-—--——---—-— >< 
»»--getID------------------------------ >< 
ea o e >< 
e A a aa aa >< 
»»--petstyleRaw----—-—---—-———-—---------- >< 
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>>--hide------------------------------- >< 
22--isEnablàd--—---—--—--—-——-—---—---------- >< 
роо аен аа >< 
»»--move(--xPos--,--yPos--4---------------------- *--)------------------------- >< 
*-,-"--showÜptions--"---* 
»»--resize(--width--,--height--4---------------------- *--)-------------------- >< 
*-,-"--showÜptions--"---* 
»»--setTitle(--new title--)--------------------------------------------------- >< 


Note: The PlainBaseDialog overrides the show() method to take an optional argument. 


»»--show------------------------------- >< 


»»--show(--'"--4-------- +--"--)------------------------------------------------ >< 
+--шоде--+ 


>>--title------------------------------ >< 


>>== 1 bee new! а leaSsSssss SS sa sas ae Saas SaaS SS SRR SSeS SS SSS SSS SS SS SS SS SSS SS ses >< 


3.3. WindowExtensions Mixin Class 


WindowExtensions is a mixin class with methods that are common to all windows. As the class name 
implies, it is an extension of the WindowBase class, providing more sophisticated window methods. It is 
inherited by both dialog and dialog control classes. 


The instance methods implemented by the WindowExtensions class are listed here as a cross reference. 
The methods are fully documented in other sections of this book. Each method listed has a link to the full 
documentation for that method and an accurate syntax diagram. 


Both the BaseDialog and the DialogControl classes inherit the WindowBase class. The DialogControl 
class is the base class for all controls. Therefore, every dialog control object and every dialog object that 
is a descendent class of the BaseDialog have the instance methods listed here. 


»»--absRect2LogRect(--left--,--top--,--right--,--bottom--)--------------------- >< 
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»»--clientToScreen(--x--,y--)-------------------------------------------------- >< 


»»--createBrush(--color--4----------------- 4--)-------------------------------- >< 


+-,brushSpecifier-+ 


>>--createFont (--+--------- +--+--------- *--—------------- +--+---------- +--)---->< 
+-,-fName-+ +-,-fSize-+ +-,"-fStyle-"-+ +-,-fWidth-+ 


»»--createFontEx(--fontName-4-------------- *-—--------------- 4--)------------- >< 
+-,-pointSize--+ +-,-additional--+ 


>>--createPen (--+------- +--+--------------- +--+------- +--)--------------------- >< 
t+-width-+ +-,-"-+-style-"-+ +-color-+ 


»»--cursor.AppStarting------------------ >< 

22--cODERUE Arrewy-—---——-—————-——----—————— >< 

>2--пигаок (ъбвв----------------<+---+ >< 

>2--вигвот Нв----+--------- >< 

22--6DFSUE Waldb---——-—-————-—-—----—-———-— >< 
>2--пигдовров-----------------+ ++ >< 

> 

>>--deleteFont (--ҺЕоп--)---------------------------------------------------- >< 

> 

»»--deleteÜObject(--0bj--)------------------------------------------------------ >< 
> 

>>--display (--+-------------- *-)----------------------------------------------- >< 


+-"-showOpts-"-+ 


»»--draw-------------------------------- >< 
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+-,-startx-,-starty-,-endx-,-endy-+ 


»»--drawLine(--dc--,--4-------4--,--4-------4--,--toX--,--toY--)--------------- >< 
+-fromX-+ +-fromY-+ 
»»--drawPie(--dc-,-x-,-y-,-x2-,-y2-,-startx-,-starty-,-endx-,-endy--)---------- >< 
»»--drawPixel(--dc--,--x--,--y--,--color--)------------------------------------ >< 
»»--fillDrawing(--dc--,--x--,--y--,--color--)---------------------------------- >< 
»»--fontColor(--color--,dc--)-------------------------------------------------- >< 
»»--fontToDC(--dc--,hFont--)--------------------------------------------------- >< 
2»--forsproundWindaw-------------------- >< 
»»--freeDC(--dc--)------------------------------------------------------------- >< 
»»--getArcDirection(--dc--)---------------------------------------------------- >< 
>>--getClientRect (--+------ *--)------------------------------------------------ >< 
+-hwnd-+ 
>>--getDC------------------------------- >< 
tah peL 2) 2, a a mee >< 
»»--getPixel(--dc--,--x--,--y--)----------------------------------------------- >< 
»»--petReot---------------------------2-- >< 
»»--getTextSizeScreen(-text--4--------- +--+------------ +--+------------- +-)---->< 


+-,-type--+ +-,-fontSrc--+ +-,-fontSize--+ 
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pages WS oC As >< 
22--BhbouEagt---—---—---———-—----------9-- >< 
>>--setHScrol1lPos(--position--+---------- 4--)---------------------------------- >< 


+-,-redraw-+ 


>>--loadBitmap (--bmpFilename--+----------- *--)--------------------------------- >< 
+-,--style--+ 


»»--logRect2AbsRect(--left--,--top--,--right--,--bottom--)--------------------- >< 
»»--objectToDC(--dc--, --0bj--)---------- >< 
»»--opaqueText (--dc--) ------------------ >< 
»»--rectangle(--dc--,--x--,--y--,--x2--,--y2--*----------- --)----------------- >< 


+-,--"FILL"-+ 


Be aes 8) 0 a a зз не >< 

>>--redrawClient (--erasebkg--)---------- >< 

»»--removeBitmap(--hBitmap--)----------- >< 

»»--restoreCursorShape(--4-------------- e ----------------------------------- >< 
+-CursorHandle-+ 

>>--screenToClient (--х--,у--)----------- >< 

>>--scroll(--cx--,--cy--)--------------- >< 

»»--setArcDirection(--dc--4------------- +=) ----------------------------------- >< 


+-,-direction-+ 


»»--setCursorPos(--x--,y--)------------- >< 


>>--setFont (--fontHandle--+--------- 4--)--------------------------------------- >< 
+-,redraw-+ 
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»»--setForegroundWindow(--hwnd--)---------------------------------------------- >< 

»»--setHScrollPos(--position--4-------- 4--)------------------------------------ >< 
+-redraw-+ 

>>--setRect (--x-- ,--y-- ,--width-- , --height--+--------------- +--)--------------- >< 


*-,-showÜption---* 


»»--setVScrollPos(--position--4-------- 4--)------------------------------------ >< 
+-redraw-+ 

>>--вранкавъ------------------------- >< 

»»--transparentText(--dc--)------------- >< 

59 Naa ы >< 

Pe mas N a шаш ызын ынчы >< 

>>-write(-x-,-y-,-txt-+--------- +-+--------- +-+--------- +--+----------- +--+------- +-) -->< 


+-,-fName-+ +-,-fSize-+ +-,-style-+ +-,-fgClr-+ +-,-bkClr-+ 


»»--writeDirect(--dc--,--xPos--,--yPos--,--text--)----------------------------- >< 
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The ooDialog framework provides a number of easy to use standard dialogs and public routines that 
allow programmers to include simple graphical elements in their Rexx applications. A few of the 
functions, like MSSleep expose functionality that can be useful in any type of Rexx application. The 
public routines can be called with a single line of code and the standard dialogs can usually be executed 
with only two lines of code. This does not require the programmer to do much set up and makes them 
simple to work with. 


The standard dialogs and public routines are listed the following table: 


Table 4-1. Standard Dialogs, and Routines 
































Public routine... 


Standard dialog... ...Description 
CheckList CheckList class 
InputBox InputBox class 
IntegerBox IntegerBox class 
ListChoice ListChoice class 
MultiInputBox MultiInputBox class 
MultiListChoice MultiListChoice class 
PasswordBox PasswordBox class 
SingleSelection SingleSelection class 
TimedMessage TimedMessage class 


...Description 
























































AskDialog AskDialog routine 
CheckList CheckList routine 
ErrorDialog ErrorDialog routine 
FileNameDialog FileNameDialog routine 
FindWindow FindWindow routine 
InfoDialog InfoDialog routine 
InputBox InputBox routine 
IntegerBox IntegerBox routine 
ListChoice ListChoice routine 
MSSleep MSSleep routine 
MultiInputBox MultiInputBox routine 
MultiListChoice MultiListChoice routine 
PasswordBox PasswordBox routine 
Play Play routine 

ScreenSize ScreenSize routine 
SingleSelection SingleSelection routine 
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Public routine... ...Description 











TimedMessage TimedMessage routine 








4.1. Standard Dialog Classes 


The standard dialog classes are: 


* TimedMessage 
* InputBox 

* PasswordBox 

* IntegerBox 

* MultilnputBox 
* ListChoice 

* MultiListChoice 
* CheckList 


* SingleSelection 


Requires: 
Use the оодР1а1п.с15 file for the standard dialog classes. 


::requires "oodPlain.cls" 


Preparation: 
Standard dialogs are prepared by using the new method of the class, which in turn invokes the Init 
method. The parameters for the new method are described for the Init method of each class. 
Execution: 


The dialog is then run by using the Execute method. For most of the standard dialogs Execute 
returns the user's input if the OK button is clicked and the null string if the Cancel button is clicked 
to terminate the dialog. If there is more than one return value, Execute returns the value 1 and stores 
the results in an attribute. Exceptions to the general rule are noted in the documentation for the 
individual dialog. 


Functions: 


Each standard dialog is also available as a callable function. These functions are described in the 
Public Routines section of this chapter. 


4.1.1. TimedMessage Class 


The TimeMessage class shows a message window for a defined duration. 
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Requires: 


oodPlain.cls is required to use this class 


Subclass: 


This class is a subclass of the PlainUserDialog class 


Execute: 
There is no return from execute for this dialog. 


The methods listed below are defined by this class. 


4.1.1.1. Init 


»»-aTimedMessage^Init(--msg--,--title--,--sleeping--*-------------- +--)---->< 
+-,-earlyReply-+ 


The Init method prepares the dialog. 


Arguments: 


The arguments are: 


message 
A string that is displayed inside the window as a message. The length of the message 
determines the horizontal size of all standard dialogs. 

title 


A string that is displayed as the window title in the title bar of the dialog 


sleeping 


A number that determines how long (in milliseconds) the window is shown. If this number is 0 
or greater, the message window is shown for that time and automatically dismisses itself. The 
programmer need take no further action. 


If the number is less than 0 then the message window is shown indefinitely. The Execute 

method returns immediately. In this case, the programmer needs to dismiss the window 

manually. This is done by invoking the stopIt method. See Example 2 below. 
earlyReply 


The optional early reply argument defaults to false. If used and if true, the execute method of 
the dialog returns immediately. This allows the code at the point where execute was invoked to 
continue. The message windows continues to display for its specified duration and then 
dismisses itself automatically. 


Example 1: 
The following example shows a window with the title of Infomation for a duration of 3 seconds: 


dlg = .TimedMessage^New("Application will be started, please wait", - 
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"Information", 3000) 
dlg~ Execute 
drop dlg 


Example 2: 


The following example shows an introductory window that displays while an application is doing its 
time consuming start up routine. Since this start up process can vary in time depending on the 
individual system, the window is set to display indefinitely. When the start up process is finished, 
the programmer dismisses the window and destroys the dialog manually. 


dlg = .TimedMessage^New("The WidgetCreator Application - loading ...", - 
"The Widget Factory", -1) 

dlg^Execute 

ret = doStartup() 

dlg^stopIt 

drop dlg 

if ret <> 0 then do 


end 


Example 3: 


The following example is a variation on Example 2. In this case the Widget Factory executives 
decided that they want their WidgeCreator splash screen to always display for 2 seconds to the 
customer and then close. The early reply argument is used so that the start up routine executes 
immediately. After 2 seconds the splash screen dismisses and the dialog is destroyed automatically. 


Note: It is not necessary to explicitly drop the dlg variable. That is shown in the other examples 
to emphasize the point that the dialog has been destroyed. 


dlg - .TimedMessage^New("The WidgetCreator Application - loading ...", - 
"The Widget Factory", 2000) 

dlg^Execute 

if doStartup() <> 0 then do 


end 


4.1.1.2. DefineDialog 


»»-aTimedMessage^DefineDialog---------------------------------- >< 


The DefineDialog method is called by the Create method of the parent class, PlainUserDialog, which in 
turn is called at the very beginning of Execute. You do not have to call it. However, you may want to 
override it in your subclass to add more dialog controls to the window. If you override it, you have to 
forward the message to the parent class by using the keyword super. 
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Example: 


The following example shows how to subclass the TimedMessage class and how to add a 
background bitmap to the dialog window: 


::class MyTimedMessage subclass TimedMessage inherit DialogExtensions 
::method DefineDialog 


self~BackgroundBitmap("mybackg.bmp", "USEPAL") 
self~DefineDialog: super () 


4.1.1.3. Execute 


»»-aTimedMessage Execute--------------------------------------- >< 


The Execute method creates and shows the message window. If the specified duration (see Init method) 
is not negative, this method destroys the dialog automatically when the duration is up. If the duration is 
less than 0, then the programmer must destroy the dialog manually by invoking the stopIt method. See 
this example for a code snippet showing the procedure. 


4.1.2. InputBox Class 


The InputBox class provides a simple dialog with a title, a message, one entry line, an OK, and a Cancel 
push button. 


Requires: 
oodPlain.cls is required to use this class 


Subclass: 


This class is a subclass of the PlainUserDialog class 


Execute: 
Returns the user’s input 


The methods listed below are defined by this class. 


4.1.2.1. Init 


»»-aInputBox^Init (--message-- ,--title-- ,--prevalue-- ,--len--)---->< 


The Init method prepares the input dialog. 
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Arguments: 


The arguments are: 


message 


A text string that is displayed in the dialog 


title 


A string that is displayed as the dialog’s title in the title bar 


prevalue 
A string to initialize the entry line. If you do not want to put any text in the entry line, just pass 
an empty string. 

len 


The width of the entry line in dialog units 


Example: 
The following example shows an InputBox dialog with the title of Input and an entry line: 


dlg = .InputBox^New("Please enter your email address", - 
"Input", "user@host.domain", 150) 

value - dlg^Execute 

say "You entered:" value 

drop dlg 


4.1.2.2. DefineDialog 


2»-alnputBox DefineDialog-------------5------c2-----cemeT--T--- >< 


The DefineDialog method is called by the Create method of the parent class, PlainUserDialog, which in 
turn is called at the very beginning of Execute. You do not have to call it. However, you may want to 
override it in your subclass to add more dialog controls to the window. If you override it, you have to 
forward the message to the parent class by using the keyword super. 


4.1.2.3. AddLine 


»»-aInputBox^AddLine(--x--,--y--,--1--)------------------------ >< 


The AddLine method is used internally to add one entry line to the dialog. 
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4.1.2.4. Execute 


22-alnputBox Ехеспёе==========-=====9=5===-=======6=6===неБнееен >< 


The Execute method creates and shows the dialog. After termination, the value of the entry line is 
returned if the user clicks the OK button; a null string is returned if the user clicks on Cancel. 


4.1.3. PasswordBox Class 


The PasswordBox class is an InputBox dialog with an entry line that echoes the keys with asterisks (*) 
instead of characters. 


Requires: 
oodPlain.cls is required to use this class 


Subclass: 


This class is a subclass of the InputBox Class 


Execute: 
Returns the user's password 


The methods are the same as for the InputBox Class, with the exception of AddLine. 


4.1.3.1. AddLine 


»»-aPasswordBox^AddLine(--x--,--y--,--1--)--------------------- >< 


The AddLine overrides the same method of the parent class, InputBox, by using a password entry line 
instead of a simple entry line. 


4.1.4. IntegerBox Class 


The IntegerBox class is an InputBox dialog whose entry line allows only numerical data. 
Requires: 
oodPlain.cls is required to use this class 


Subclass: 


This class is a subclass of the InputBox Class class 


Execute: 


Returns the user’s numeric input 
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The methods are the same as for the InputBox Class class, with the exception of Validate. 


4.1.4.1. Validate 


>>-alntegerBox validaté---—--—-----—-—---------—------ SSeS ass >< 


The only method this subclass overrides is Validate, which is one of the automatically called methods of 
PlainUserDialog. It is invoked by the OK method, which in turn is called in response to a push button 
event. This method checks whether or not the entry line contains a valid numerical value. If the value is 
invalid, a message window is displayed. 


4.1.5. MultilnputBox Class 


The MultiInputBox class is a dialog that provides a title, a message, and one or more entry lines. After 
execution of this dialog you can access the values of the entry lines. 


Requires: 


oodPlain.cls is required to use this class 


Subclass: 


This class is a subclass of the "PlainUserDialog" class 


Execute: 


Returns 1 (if OK was clicked). The values entered by the user are stored in attributes matching the 
labels of the entry lines. 


The methods are the same as for the InputBox Class class, with the exception of Init. 


4.1.5.1. Init 


»»-aMultilnputBox^Init(--message--,--title--,--labels.--,--datas.--» 
>--+-------- 4--)-------------------------------------------------- >< 
+-,--len-+ 


The Init method is called automatically whenever a new instance of this class is created. It prepares the 
dialog. 
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Arguments: 


The arguments are: 


message 
A text string that is displayed on top of the entry lines. Use it to give the user advice on what to 
do. 

title 


A text string that is displayed in the title bar. 


labels. 


A stem variable containing strings that are used as labels on the left side of the entry lines. 
Labels. 1 becomes the label for the first entry line, labels.2 for the second, and so forth. 


datas. 


A stem variable (do not forget the trailing period) containing strings that are used to initialize 
the entry lines. The entries must start with 101 and continue in increments of 1. 


len 


The length of the entry lines. All entry lines get the same length. 


Example: 


The following example creates a four-line input box. The data entered is stored in the object 
attributes that are displayed after dialog execution. 


lab.1 
lab.3 


"First name" ; lab.2 "Last name " 


"Street and City" ; lab.4 - "Profession:" 


addr.101 = "John" ; addr.102 = "Smith" ; addr.103 = "" 
addr.104 


"Software Engineer" 


dlg - .MultiInputBox^new("Please enter your address", , 
"Your Address", lab., addr.) 
if dlg^execute = 1 then do 
say "The address is:" 
say dlg^firstname dlg^lastname 
say dlg^StreetandCity 
say dlg^Profession 
end 


4.1.6. ListChoice Class 


The ListChoice class provides a dialog with a list box, an OK, and a Cancel button. The selected item is 
returned if the OK push button is used to terminate the dialog. 
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Requires: 


oodPlain.cls is required to use this class 


Subclass: 


This class is a subclass of the "PlainUserDialog" class 


Execute: 
Returns the user's choice or a null string 


The method listed below is defined by this class. 


4.1.6.1. Init 


»»-aListChoice^Init(--message--,--title--,--input.-------------- ? 
>--+--------------------------------------------------- +------- >< 
+-,--+------ +--+------------------------------- +--)-+ 
+-1епх-+ +-,--+------ +--+-------------- +-+ 
*-leny-* +-,--preselect-+ 


The Init method is used to initialize a newly created instance of this class. 


Arguments: 


The arguments are: 


message 


A text string that is displayed on top of the list box. Use it to give the user advice on what to do. 


title 


A text string for the dialog’s title 


input. 


A stem variable (do not forget the trailing period) containing string values that are inserted into 
the list box 


lenx, leny 


The size of the list box in dialog units 
preselect 


Entry that is selected when list pops up 


Example: 


The following example creates a list choice dialog box where the user can select exactly one dessert: 


lst.1 = "Cookies"; 151.2 = "Pie"; 151.3 = "Ice cream"; 151.4 = "Fruit" 
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dlg = .ListChoice^new("Select the dessert please","YourChoice",lst., , ,"Pie") 
say "Your ListChoice data:" д1р execute 


4.1.7. MultiListChoice Class 


The MultiListChoice class is an extension of the ListChoice class. It makes it possible for the user to 
select more than one line at a time. The Execute method returns the selected items’ indexes separated by 
blank spaces. The first item has index 1. 


Requires: 


oodPlain.cls is required to use this class 


Subclass: 


This class is a subclass of the ListChoice Class 


Execute: 


Returns the index numbers of the entries selected 


Preselect: 


Indexes of entries, separated by a blank, that are to be preselected. The first entry has index 1 and 
the rest are increments of one. 


The methods are the same as for the ListChoice Class class, except that Execute returns the index 
numbers of the selected entries. 


Example: 


The following example creates a multiple list choice box where the user can select multiple entries: 


lst.1 = "Monday" ; lst.2 = "Tuesday" ; lst.3 = "Wednesday" 

lst.4 = "Thursday" ; 151.5 = "Friday" ; Ilst.6 = "Saturday" 

lst.7 = "Sunday" 

dlg = .MultiListChoice^new("Select the days you are working this week", , 


"YourMultipleChoice",lst., , ,"2 5") 
S = dlg^execute 
if s <> "" then do while s \= "" 
parse var s res s 
say lst.res 
end 


4.1.8. CheckList Class 


The CheckList class is a dialog with a group of one or more check boxes. 


ooRexx OODialog Reference Version 4.0.0 39 


Chapter 4. Standard Dialogs, and Public Routines 


Requires: 


oodPlain.cls is required to use this class. 


Subclass: 


This class is a subclass of the "PlainUserDialog" class. 


Execute: 


Returns 1 (1f OK was clicked). The check boxes selected by the user are marked in a stem variable 
with the value 1. 


The method listed below is defined by this class. 


4.1.8.1. Init 


>>-aCheckList~ Init (--message-- ,--title--,--labels.--,--datas.--> 
>>--+------------------------ 4--)----------------------------- >< 
+-,--+-----+--+--------+-+ 
+-len-+ +-,--шах-+ 
Arguments: 


The arguments are: 


message 


A text string that is displayed on top of the check box group. Use it to give the user advice on 


what to do. 
title 
A text string for the dialog’s title 
labels. 
A stem variable (do not forget the trailing period) containing all the labels for the check boxes 
datas. 
This argument is a stem variable (do not forget the trailing period) that you can use to preselect 
the check boxes. The first check box relates to stem item 101, the second to 102, and so forth. 
A value of | indicates selected, and a value of 0 indicates deselected. 
For example, Datas.103=1 indicates that there is a check mark on the third box. 
len 


Determines the length of the check boxes and labels. If omitted, the size is calculated to fit the 
largest label. 
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max 


The maximum number of check boxes in one column. If there are more check boxes than max 
- that is, labels. has more items than the value of max - this method continues with a new 
column. 


Example: 


The following example creates and shows a dialog with seven check boxes: 


lst.1 = "Monday"; lst.2 = "Tuesday"; lst.3 = "Wednesday" 
lst.4 = "Thursday"; lst.5 = "Friday"; I1st.6 = "Saturday" 
lst.7 = "Sunday" 


do i = 101 to 107 
chk.i = 0 
end 


dlg = .CheckList^new("Please select a day!","Day of week",lst., chk.) 
if dlg^execute = 1 then do 
say "You selected the following day(s): " 
do i = 101 to 107 
a = i-100 
if chk.i = 1 then say lst.a 
end 
end 


4.1.9. SingleSelection Class 


The SingleSelection class shows a dialog that has a group of radio buttons. The user can select only one 
item of the group. 


Requires: 
oodPlain.cls is required to use this class 


Subclass: 


This class is a subclass of the "PlainUserDialog" class 


Execute: 
Returns the number of the radio button selected 


The method listed below is defined by this class. 


4.1.9.1. Init 


»»-aSingleSelection^Init(--message--,--title--,--labels.--,--data--» 


»--—------------------------ 4--)------------------------------- >< 
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+-,--+-----+--+--------+-+ 
+-len-+ +-,--шах-+ 
Arguments: 


The arguments are: 


message 
A text string that is displayed on top of the radio button group. Use it to give the user advice on 
what to do. 

title 


A text string for the title bar 


labels. 


This argument is a stem variable containing all labels for the radio buttons 


data 
You can use this argument to preselect one radio button. A value of 1 selects the first radio 
button, a value of 2 selects the second, and so on. 

len 
Determines the length of the check boxes and labels. If omitted, the size is calculated to fit the 
largest label. 

max 


The maximum number of radio buttons in one column. If there are more radio buttons than 
max - that is, labels. has more items than the value of max - this method continues with a new 
column. 


Example: 


The following example creates and executes a dialog that contains a two-column radio button group. 
The fifth radio button (the button with the label May) is preselected. 


mon.1 = "January" ; mon.2 = "February" ; mon.3 = "March" 
mon.4 = "April" ; mon.5 = "May" ; mon.6 = "June" 
mon.7 = "July" ; mon.8 = "August" ; mon.9 = "September" 
mon.10= "October" ; mon.11- "November" ; mon.12- "December" 
dlg - .SingleSelection^new("Please select a month!", 


"Single Selection", mon., 5, , 6) 
5 = dlg^execute 
say "You Selected the month: " mon.s 
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4.2. Public Routines 


The routines listed in this section can be used in any Rexx program. They are designed to be even easier 
to use than the standard dialogs or the external functions. They do not require that an ooDialog dialog be 
initialized prior to their use, or that any ooDialog dialog be used in the program at all. The programmer 
does not have to register any functions to use these routines. 


Requires: 


Use a requires directive for the ooDialog.cls file in an Rexx program to use any of these routines. 


::requires ooDialog.cls 


4.2.1. Play Routine 


This routine is used to play audio sounds. 


»»-Play(--4---------- +--+4--------- Е) ање >< 
+-fileName-+ +-,--YES--+ 
+-,--LOOP-+ 


The Play routine can be used to play an audio file using the Windows multimedia capabilities. See also 
the PlaySoundFile external function. 


The named file is searched for in the current directory and in the directories of the SOUNDPATH 
environment variable. 


Arguments: 


The arguments are: 


fileName 


The file name of an audio (.WAV) file. The file is searched for in the current directory and in 
the directories listed in the SOUNDPATH environment variable. If this argument is omitted, 
the currently playing sound file is stopped. 


option 


You can set the last argument to: 


YES 
This plays the audio file asynchronously. 


LOOP 


Plays the audio file asynchronously and repeats it in a loop. You can stop the loop by 
calling Play again omitting all arguments. 
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Example: 
The following example plays a welcoming message: 


rc = play("Welcome.wav") 


4.2.2. InfoDialog Routine 


Pops up a message box containing the specified text and an OK button. 


»»-InfoDialog(--info text--)---------------------------------- >< 


Argument: 


The only argument is: 


info_text 


Text to be displayed in the message box. 


4.2.3. ErrorDialog Routine 
Pops up a message box containing the specified text, an OK button, and an error symbol. 


»»-ErrorDialog(--error text--)-------------------------------- >< 


Argument: 


The only argument is: 


error_text 


Text to be displayed in the message box. 


4.2.4. AskDialog Routine 
Pops up a message box containing the specified text, a Yes button, and a No Button. 


»»-AskDialog(--question--4------------------- 4--)------------- >< 
+--, defaultbutton--+ 
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Arguments: 
The only argument is: 
question 
Text to be displayed in the message box. 


defaultbutton 


Specifies which button, the Yes or the No button, has the default focus when the message box 
pops up. This argument can be Yes or No and is optional. If the argument is omitted, the Yes 
button will be given the focus. Only the first letter of the option is needed and case is not 
significant. 


Return Values: 


The No button has been selected. 


The Yes button has been selected. 


4.2.5. FileNameDialog Routine 


Causes a file selection dialog box to appear. 


»»-FileNameDialog(--4--------- *-—-------------------------------- +--> 
+-selfile-+  4-,--4-------- +--+------------- +-+ 
+-parent-+ +-,--filemask-+ 
>--+----------------------------------------------------------------- > 
+-,--+------------ +--+---------- +--+----------------- +------------ > 
+-loadorsave-+ +-,--title-+ +-,--defExtension-+ 
>--+----------------------------------- *--)------------------------- >< 
>--+---------------- +--+------------ +--+ 
+-,--multiSelect-+ +-,--sepChar-+ 
Arguments: 


The arguments are: 


selfile 


Preselected file name and / or initial directory information. 
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This argument places a preselected file name in the "File name" field of the file selection 
dialog. In addition this argument can also be used to specify the initial directory (folder) the 
dialog opens in. 


When this argument contains no path information, then the File name field will contain the 

argument and the initial directory is determined by the operating system. Which directory the 
operating system picks varies slightly between Windows 98, Windows NT, Windows XP, etc. 
But, in general, it will be a directory previously used in one of the Windows common dialogs, 
or a directory in the users My Documents. (The exact behavior is documented by Microsoft.) 


If the argument contains file name and path information, the initial directory will be 
determined by the path information and the File name field will contain the file information. 
When the selfile argument contains only path information and no file name information, i.e. the 
argument ends with a back slash ("\"), then the initial directory will be that path and the File 
name field will be left blank. 


In cases where the argument contains incorrect path information the initial directory is 
determined as if no path information had been supplied and the entire value of the argument is 
placed in the File name field. 


Note: Windows treats normal wild card characters as valid for file names. Therefore, values 
such as C:\*.* or C:\Windows\*.exe are acceptable for this argument. 


parent 


Handle to the parent window. 


filemask 
Pairs of null-terminated filter strings. 


The first string in each pair is a display string that describes the filter (for example, "Text 
Files"), and the second string specifies the filter pattern (for example, "*.TXT"). To specify 
multiple filter patterns for a single display string, use a semicolon to separate the patterns (for 
example, "*.TXT;*.DOC;*.BAK"). A pattern string can be a combination of valid file name 
characters and the asterisk (*) wildcard character. Do not include spaces in the pattern string. 


If omitted, "Text Files (*.TXT)"'O'x"*.TXT"'O'x"All Files (*.*)''O'x"*.*" 15 used as the 
filter. 
loadorsave 


Specifies which dialog should be displayed, the File Open Dialog (the default) or the File Save 
Dialog. If the File Save Dialog is not explicitly requested the default File Open Dialog is 
always presented. Only the first letter of the argument is needed and case is not significant. For 
historic reasons this argument can also be 1 (File Open Dialog) or 0 (File Save Dialog.) 


Load or 1 
Display the File Open Dialog (default). 


46 ooRexx OODialog Reference Version 4.0.0 


Chapter 4. Standard Dialogs, and Public Routines 


Save or 0 


Display the File Save Dialog. 


title 
The window title. The default is "Open a File" or "Save File As", depending on what is 
specified for loadorsave. 
defExtension 
The default extension that is added if no extension was specified. The default is TXT. 
multiSelect 
Specifies if the File Open Dialog allows selection of multiple files. Normally, the open dialog 
allows the user to select one file only. This can be changed by specifying "MULTI" for this 
option. Only the first letter is needed and case is not significant. 
MULTI 
Multiple file selection is allowed. This option is ignored for File Save Dialogs. If the user 
selects multiple files, the result is then path file! file2 file3 ... 
sepChar 


Specifies the separation character for the returned path and file names. This is needed for file 
names with blank characters. If this argument is omitted, the separation character is a blank. If 
the argument is specified, the returned path and file name uses this separation character. For 
example, if you specify "#" as the separation character, the return string might look as follows: 


C:\WINNT#file with blank.ext#fileWithNoBlank.TXT 


Return value: 
Returns the selected file name or 0 if the user cancels the dialog. Open File dialogs with multiple 
selection return path file! file2 file3 ... when the user selects multiple files. 

Notes: 


If the user changes directory with the File Open or File Save dialog, then the current directory of the 
Rexx program will be changed. This is the behavior of the underlying Windows dialog, which is 
designed to work that way. The ooDialog programmer should be aware of this behavior and insert 
code to change the directory back if that is needed. For example: 


curdir = directory O 
file = FileNameDialog("*.pdf", , "Adobe PDF Files"’0’x"*.pdf"’0’x) 
call directory curdir 


4.2.6. FindWindow Routine 


Searches the Windows application list for a specific window and returns its handle. 


»»-FindWindow(--Caption--)------------------------------------ >< 
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Argument: 


The only argument is: 


Caption 


Caption of the window that is to be searched. 


Return value: 


Handle of the window or 0 if the window was not found. 


4.2.7. ScreenSize Routine 
Obtains the screen size in dialog units and in pixels 


»»-ScreenSize()----------------------------------------------- >< 


Argument: 


This function takes no arguments. 


Return value: 
An array containing the screen size. The size in dialog units of the width is at index 1 and the height 
in dialog units is at index 2. The size in pixels of the width is at index 3 and the height in pixels is at 
index 4. 

Example 
Get the screen size and display it to the user. 


size = screenSize() 

say 

say ?The monitor is’ size[1] ’dialog units wide and’ size[2] ’dialog units high.’ 
say ’The monitor is’ size[3] ’pixels wide and’ size[4] ’pixels high.’ 


4.2.8. SystemMetrics Routine (deprecated) 


Note: This routine is deprecated. It is replaced by the functionally equivalent getSystemMetrics() 
method of the .DIgUtil class. Do not use this routine in new code. Try to migrate existing code to to 
the .D1gUtil^getSystemMetrics O method. This routine may not exist in future versions of ooDialog. 


4.2.9. MSSleep Routine 


Sleeps for the specified number of milliseconds. 
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»»-MSSleep(--duration--)-------------------------------------- >< 


Argument: 


The only argument is: 


duration 


The time in milliseconds to sleep. 


Return value: 


This function always returns 0. 


4.2.10. TimedMessage Routine 


The TimedMessage routine provides a shortcut to invoke a TimedMessage dialog as a function: 
ret = TimedMessage("We are starting...","Please wait" ,3000) 


The parameters are the same as described in the Init method of the TimedMessage class. 


The function returns 0, always, when the duration is non-negative. When the duration is less than 0, the 
function returns a reference to the TimedMessage dialog object. This is needed in order for the 
programmer to manually dismiss the dialog. Below are the same 3 examples listed for the TimedMessage 
dialog, modified to work with the public routine: 


Example 1: 


The following example shows a window with the title of Infomation for a duration of 3 seconds: 


ret = timedMessage("Application will be started, please wait", - 
"Information", 3000) 


Example 2: 


The following example shows an introductory window that displays while an application is doing its 
time consuming start up routine. Since this start up process can vary in time depending on the 
individual system, the window is set to display indefinitely. When the start up process is finished, 
the programmer dismisses the window and destroys the dialog manually. Note how a reference to 
the TimedMessage dialog is returned. The programmer only needs to use this to dismiss / destroy the 
dialog 


dlg - timedMessage("The WidgetCreator Application - loading ...", - 
"The Widget Factory", -1) 

ret = doStartup() 

dlg^stopIt 

if ret <> 0 then do 


end 
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Example 3: 


The following example is a variation on Example 2. In this case the Widget Factory executives 
decided that they want their WidgeCreator splash screen to always display for 2 seconds to the 
customer and then close. The early reply argument is used so that the start up routine executes 
immediately. After 2 seconds the splash screen dismisses and the dialog is destroyed automatically. 


ret = timedMessage("The WidgetCreator Application - loading ...", - 
"The Widget Factory", 2000) 


if doStartup() <> 0 then do 


end 


4.2.11. InputBox Routine 


A shortcut function to invoke an InputBox dialog as a function: 
say "Your name:" InputBox("Please enter your name","Personal Data") 


The parameters are described in the Init method of theInputBox class. 


4.2.12. PasswordBox Routine 


A shortcut to invoke a PasswordBox dialog as a function: 


pwd = PasswordBox("Please enter your password","Security") 


The parameters are described in the Init method of the InputBoxclass. 


4.2.13. IntegerBox Routine 


A shortcut to invoke an IntegerBox dialog as a function: 


say "Your age:" IntegerBox("Please enter your age","Personal Data") 


The parameters are described in the Init method of the InputBoxclass. 


4.2.14. MultilnputBox Routine 


Provides a shortcut function to invoke a MultiInputBox dialog: 


res = MultiInputBox("Enter your address","Personal Data", , 
.array^of("&First name","Last &name","&City"), , 
.array^of("John","Smith","San Jose"), 100) 

if res \= .Nil then do entry over res 

say "Address-line[]l- " entry 
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end 
The parameters are described in the Init method of the MultiInputBoxclass. However, instead of using 


stems, arrays are used for input. 


The user’s input to the dialog is also returned in an array. Note this other difference from the 
MultiInputBox dialog: if the user cancels the dialog .nil is returned rather than the empty string. 


4.2.15. ListChoice Routine 


The ListChoice function provides a shortcut to invoke a ListChoice dialog: 


day = ListChoice("Select a day","My favorite day", , 
.array~of ("Monday", "Tuesday", "Wednesday" , "Thursday", , 
"Friday","Saturday","Sunday") , , ,"Thursday") 
say "Your favorite day is" day 


The parameters are described in the Init method of the ListChoiceclass. However, instead of an input 
stem an array is passed into the function. 


If the user cancels the dialog .nil is returned rather than the empty string. 


4.2.16. MultiListChoice Routine 


Provides a shortcut to invoke a MultiListChoice dialog as a function: 


days = MultiListChoice("Select days","My TV Days", , 
.array^of("Monday","Tuesday","Wednesday", , 
"Thursday","Friday","Saturday","Sunday"), , ,"2 5") 
if days <> .Nil then do day over days 
say "TV day =" day 
end 


The parameters are described in the Init method of the MultiListChoiceclass. However, instead of 
stems, arrays are passed into the function. 


If the user cancels the dialog .nil is returned rather than the empty string. 


4.2.17. CheckList Routine 


A shortcut function to invoke the CheckList dialog: 


>>--CheckList (--message-- ,--title-- ,--labels-- ,-+----------- tae 
+-,--checks-+ 
>>--+-----------------------< +--)------------------- >< 
+-,--+-----+--+--------+—-+ 
+-len-+ +-,--шах-+ 
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Arguments: 


The arguments are similar to what is described in the Init method of the CheckListclass. However, 
instead of stems, arrays are passed into and returned from the function. 


message 
A text string that is displayed on top of the check box group. It could be used, for example, to 
give the user a hint as to what to do. 

title 


A text string for the dialog’s title 


labels 


An array containing the labels, in order, for each of the check boxes. The dialog will contain a 
check box for each label. 


checks 


This argument is an array that allows you to pre-check any of the check boxes. For each index 
in this array whose item is .true, (or 1,) the check box at the corresponding index in the 
labels array will be checked. For any index that is not .true , the corresponding check box 
will not be checked. This means that the programmer only needs to put a .true at the indexes 
where he wants the check boxes checked. All the other indexes can be left empty. 


len 
Determines the length (in dialog units) of the check boxes and labels. If omitted, the size is 
calculated to fit the largest label. 

max 


The maximum number of check boxes in one column. If there are more check boxes than max, 
that is, if labels has more items than the value of max, the check boxes will be put into 
columns. Each column will contain no more than the number of check boxes specified by max. 


Return value: 


If the user cancels the dialog, then .nil is returned. If the user clicks the okay button, then an array 
is returned. The array will be the same size as the input labels array. Each index of the returned 
array will contain .true if the corresponding check box was checked by the user or will contain 

. false if the check box was not checked. 


Example 
The following example show how to use the CheckList public routine: 
weekdays = .array~of("Monday","Tuesday","Wednesday","Thursday", - 


"Friday","Saturday", "Sunday") 


-- Monday and Tuesday will be checked, all the rest will not be checked. 
checks = .array^of(.true, .true, .false) 

checks[5] = 0 

checks[7] = а? 


52 ooRexx OODialog Reference Version 4.0.0 


Chapter 4. Standard Dialogs, and Public Routines 


-- The labels will be 60 dialog units wide and there will be at most 4 check 
-- boxes in a column. (Only 7 check boxes, so 2 columns, the first with 4 
-- check boxes, the second with 3.) 


days = CheckList("Check the days", "Working Days", weekdays, checks, 60, 4) 


if days <> .Nil then do i = 1 to days^items 
if days[i] then say "Working day =" weekdays[i] 
end 


::requires "oodPlain.cls" 


4.2.18. SingleSelection Routine 


The SingleSelection function provides a shortcut means to invoke a SingleSelection dialog 


months = .array^of("Jan","Feb","Mar","Apr","May","Jun", - 
"Jul" › "Aug" ; "бер" я "Ост" > "Nov" А "Dec") 

title = "Month You Were Born" 

groupBoxLabel = "Check your birth month" 

selectedRadioButton = 3 


m = SingleSelection(groupBoxLabel, title, months, selectedRadioButton, , 6) 
if m == "" then 

say "The user canceled the dialog." 
else 

say "Born in month" m "=" months [m] 


::requires "oodPlain.cls" 


The parameters are described in the Init method of Ше SingleSelectionclass. However, instead of an 
input stem an array is passed into the function. 


4.3. External Functions (deprecated) 


Do not directly use any of the ooDialog external functions. 


The ooDialog documentation prior to ooDialog 4.0.0 documented ten external functions as callable 
functions that can be used in your Object Rexx programs. It then mentioned in passing that the Public 
Routines were a more convenient way to use these functions. It was noted that the external routines were 
registered automatically when the first dialog was initialized, but if the programmer wanted to use the 
external routines when no dialog was created, he could register the individual functions using RxFuncAdd. 


The 3.2.0 documentation expounded on that a little and also mentioned that there were other external 
functions, noting that it would be difficult for ooDialog programmers to use these other functions unless 
they were experienced C programmers. In hindsight that was a mistake. Each of the external functions 
has a matching public routine. No mention of the external functions should have been made. Instead, 
only the public routines should have been documented. 
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The reason for this is simple, the external functions are being removed. Prior to 4.0.0, ooDialog was 
implemented using the original external naitve API. This API was useful, but somewhat limiting. 
Particularly when used with the object-orientated paradigm. ooRexx 4.0.0 introduces a new native API 
that is much more robust and flexible. Using this new API makes writing exernal packages like ooDialog 
much easier. 


ooDialog is in the process of being converted to use this new API. All of the external functions will be 
removed. If your programs directly uses any of the undocumented external functions, at some point in 
future they will not work with a new release of ooDialog. 


The documented external functions will be available as deprecated functions, with the possibility of 
their removal in the future. However, they will simply map to the corresponding public routine. The 
programmer can remove this extra level of indirection by calling the public routine directly. It would be 
nice if ooDialog did not have to drag along this baggage forever into the future. 


It is no longer necessary to use RxFuncAdd(). Doing so is a nop. Likewise, registering InstMMFuncs() 
and calling it does nothing. The ooDialog programmer should remove any references to RxFuncAdd 
(when used to register any ooDialog external function,) апа InstMMFuncs in their code as the 
opportunity arises. 


4.3.1. InfoMessage (deprecated) 


Note: This method is deprecated. See this explanation. Use the public routine InfoDialog. Do not use 
this method in new code. Try to migrate existing code to InfoDialog. This function may not exist in 
future versions of ooDialog. 


4.3.2. ErrorMessage (deprecated) 


Note: This method is deprecated. See this explanation. Use the public routine ErrorDialog. Do not 
use this method in new code. Try to migrate existing code to ErrorDialog. This function may not exist 
in future versions of ooDialog. 


4.3.3. YesNoMessage (deprecated) 


Note: This method is deprecated. See this explanation. Use the public routine AskDialog. Do not use 
this method in new code. Try to migrate existing code to AskDialog. This function may not exist in 
future versions of ooDialog. 
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4.3.4. GetScreenSize (deprecated) 


Note: This method is deprecated. See this explanation. Use the public routine ScreenSize. Do not 
use this method in new code. Try to migrate existing code to ScreenSize This function may not exist 
in future versions of ooDialog. 


4.3.5. getSysMetrics (deprecated) 


Note: This function is deprecated. It is replaced by the functionally equivalent getSystemMetrics() 
method of the .DIgUtil class. Do not use this function in new code. Try to migrate existing code to to 
the .D1gUtil^"getSystemMetrics O method. This function may not exist in future versions of ooDialog. 


4.3.6. PlaySoundFile (deprecated) 


Note: This method is deprecated. See this explanation. Use the public routine Play. Do not use this 
method in new code. Try to migrate existing code to Play. This function may not exist in future 
versions of ooDialog. 


4.3.7. PlaySoundFilelnLoop (deprecated) 


Note: This method is deprecated. See this explanation. Use the public routine Play. Do not use this 
method in new code. Try to migrate existing code to PLay. This function may not exist in future 
versions of ooDialog. 


4.3.8. StopSoundFile (deprecated) 


Note: This method is deprecated. See this explanation. Use the public routine Play. Do not use this 
method in new code. Try to migrate existing code to Play. This function may not exist in future 
versions of ooDialog. 
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4.3.9. GetFileNameWindow (deprecated) 


Note: This method is deprecated. See this explanation. Use the public routine FileNameDialog. Do 
not use this method in new code. Try to migrate existing code to FileNameDialog. This function may 
not exist in future versions of ooDialog. 


4.3.10. SleepMS (deprecated) 


Note: This method is deprecated. See this explanation. Use the public routine MSSleep. Do not use 
this method in new code. Try to migrate existing code to MSSleep. This function may not exist in 
future versions of ooDialog. 


4.3.11. WinTimer (deprecated) 


Note: This method is deprecated. See this explanation. There is no replacement for this function. Do 
not use this method in any code. 


The implementation of this function is poor. It uses 100% of the CPU while waiting. It should be 
possible to provide this functionality without consuming all the CPU. A future version of ooDialog may 
provide a proper implementation for the functionality of waiting on a repeating timer. 
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The BaseDialog class implements base methods for all dialogs regardless of whether the dialog is 
implemented as a binary resource, a resource script, or created dynamically. Binary (compiled) resources 
are stored in a DLL. A dialog is created dynamically by using Add... methods. Dialogs that are 
implemented using a resource script (.RC) are generated semi-dynamically. 


BaseDialog is an abstract class. You cannot use it to execute a Windows dialog but have to use one of its 
subclasses. 


See the subclasses UserDialog Class, ResDialog Class, and RcDialog Class for additional information. 


Requires: 
BaseDlg.cls is the source file of this class. 


::requires oodialog.cls 


Attributes: 


Instances of the BaseDialog class have the following attributes: 


AutoDetect 
Automatic data field detection on (=1, default) or off (=0). For the UserDialog subclass the 
default is off and Connect... methods or a resource script are usually used. 
AutomaticMethods 
A queue containing the methods that are started concurrently before the execution of the 
dialog. 
BkgBitmap 
The handle to a bitmap that is displayed in the dialog’s background. 


BkgBrushBmp 


The handle to a bitmap that is used to draw the dialog’s background. 


ConstDir 


A directory object whose indexes are symbolic IDs. The entry for each index is the numerical 
value of the symbolic ID. Once a symbolic ID is added to the Constdir directory, the symbolic 
ID can be used in place of the numeric value in any method of the ooDialog classes that 
requires a resource ID. 


A few symbolic IDs are pre-defined by ooDialog and are present in the ConstDir directory of 
all ooDialogs. See the table, Symbolic IDs Used by ooDialog, for a list of these IDs. The 
programmer can add symbolic IDs to this directory by using #define statements in a resource 
script or a header file. Of course, symbolic IDs can also be added directly in the program as the 
following code snippet shows: 


::method Init 
forward class (super) continue 
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self^ConstDir["ID GB"] = 101 
self^ConstDir["ID СВ REGINA"] = 107 
self^ConstDir["ID. CB REGINALD"] = 111 
self^ConstDir["ID СВ OOREXX"] = 115 


::method defineDialog 


self^addGroupBox(10, 20, 150, 90, "Pick an interpreter", "BORDER", 10 GB) 


self^addCheckBox(ID CB. REGINA, "cbi", 30, 40, , , "Regina", "GROUP") 
self^addCheckBox(ID. СВ REGINALD, "cb2", 30, 60, , , "Reginald") 
self^addCheckBox(ID. CB OOREXX, "cb3", 30, 80, , , "ooRexx") 

::method ok 


oorexxCB = self^getCheckControl(ID. CB. OOREXX) 
if oorexxCB^checked then 
say "You picked the right interpreter." 
DataConnection 
A protected attribute to store connections between dialog items and the attributes of the dialog 
instance. 
DigHandle 
The handle to the dialog. 


Finished 


When this is set to 1, Ok or Cancel will terminate the dialog on exit. 


InitCode 


After the Init method has executed the InitCode attribute will be 0 if the object initialization 
detected no errors. The attribute will be non-zero if initialization failed or an error was 
detected. The programmer should always check the InitCode attribute after instantiating a 
dialog object. If the attribute is not zero, then the object was not initialized correctly and its 
behavior is undefined. 


After the dialog is finished, the attribute will be 1 if terminated with Ok, 2 if terminated with 
Cancel. 


IsExtended 


A protected attribute that is true (=1) if the graphics extension is installed. 


UseStem 


A protected attribute that is true (=1) if a stem variable was passed to Init. 
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See Public Routines for a description of the audio Play routine. 


Cross Reference: 


The following table cross references the descriptions for the BaseDialog class methods, attributes, 


and instance methods: 


Table 5-1. BaseDialog Reference 








































































































Item... ... description 
Class Method Link 
getFontName (Class method) getFontName 
getFontSize (Class method) getFontSize 
setDefaultFont (Class method) setDefaultFont 
Attributes Link 
fontName (Attribute) fontName 
fontSize (Attribute) fontSize 
Instance Methods Link 
AbsRect2LogRect AbsRect2LogRect 
AddAttribute AddAttribute 
AddAutoStartMethod AddAutoStartMethod 
AddComboEntry AddComboEntry 
AddListEntry AddListEntry 
addUserMsg addUserMsg 
assignWindow (deprecated) AssignWindow (deprecated) 
AsyncMessageHandling AsyncMessageHandling 
AutoDetection AutoDetection 
BackgroundBitmap BackgroundBitmap 
BackgroundColor BackgroundColor 
Cancel Cancel 
CaptureMouse CaptureMouse 
Center Center 
ChangeBitmapButton ChangeBitmapButton 
ChangeComboEntry ChangeComboEntry 
ChangeListEntry ChangeListEntry 
CheckMenultem CheckMenultem 
Clear Clear 
ClearButtonRect ClearButtonRect 
ClearMessages ClearMessages 
ClearRect ClearRect 
ClearWindowRect ClearWindowRect 
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Item... ... description 
ClientToScreen ClientToScreen 
CombineELwithSB CombineELwithSB 
ComboAddDirectory ComboAddDirectory 
ComboDrop ComboDrop 
ConnectAIISBEvents ConnectAIISBEvents 
ConnectAnimatedButton ConnectAnimatedButton 
ConnectBitmapButton ConnectBitmapButton 
ConnectButton ConnectButton 
ConnectCheckBox ConnectCheckBox 
connectComboBox connectComboBox 
ConnectControl ConnectControl 
ConnectDraw ConnectDraw 
ConnectEntryLine ConnectEntryLine 
ConnectFKeyPress ConnectFKeyPress 
ConnectHelp ConnectHelp 
ConnectKeyPress ConnectKeyPress 
ConnectList ConnectList 
ConnectListBox ConnectListBox 
ConnectListLeftDoubleClick ConnectListLeftDoubleClick 
ConnectMenultem ConnectMenultem 
ConnectMouseCapture ConnectMouseCapture 
ConnectMove ConnectMove 
ConnectMultiListBox ConnectMultiListBox 
ConnectPosChanged ConnectPosChanged 
ConnectRadioButton ConnectRadioButton 
ConnectResize ConnectResize 
ConnectScrollBar ConnectScrollBar 
CreateBrush CreateBrush 
createFontEx createFontEx 
CreatePen CreatePen 





Cursor_AppStarting 


Cursor_AppStarting 





Cursor_Arrow 


Cursor_Arrow 





Cursor_Cross 


Cursor_Cross 





Cursor_No 


Cursor_No 





CursorPos 


CursorPos 





Cursor_Wait 


Cursor_Wait 





Delnstall 


Delnstall 








DeleteComboEntry 





DeleteComboEntry 
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Item... ... description 
DeleteFont DeleteFont 
DeleteListEntry DeleteListEntry 
DeleteObject DeleteObject 
DetermineSBPosition DetermineSBPosition 
Disable Disable 
DisableItem DisableItem 
DisableMenultem DisableMenultem 
DisconnectKeyPress DisconnectKeyPress 
DisplaceBitmap DisplaceBitmap 
Display Display 

Draw Draw 
DrawAngleArc DrawAngleArc 
DrawArc DrawArc 
DrawBitmap DrawBitmap 
DrawButton DrawButton 
DrawLine DrawLine 

DrawPie DrawPie 

DrawPixel DrawPixel 

Dump Dump 

Enable Enable 
EnableMenultem EnableMenultem 
EnableItem EnableItem 
EndAsyncExecution EndAsyncExecution 
EnsureVisible EnsureVisible 
Execute Execute 
ExecuteAsync ExecuteAsync 
FillDrawing FillDrawing 
FindComboEntry FindComboEntry 
FindListEntry FindListEntry 
FocusItem FocusItem 
FontColor FontColor 
FontToDC FontToDC 
ForegroundWindow ForegroundWindow 
FreeButtonDC FreeButtonDC 
FreeDC FreeDC 
FreeWindowDC FreeWindowDC 
Get Get 
GetArcDirection GetArcDirection 
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Item... ...description 
GetAttrib GetAttrib 
GetBitmapSizeX GetBitmapSizeX 
GetBitmapSizeY GetBitmapSizeY 
GetBmpDisplacement GetBmpDisplacement 
GetButtonDC GetButtonDC 
GetButtonRect GetButtonRect 
GetClientRect GetClientRect 
GetCheckBox GetCheckBox 
GetComboEntry GetComboEntry 
GetComboltems GetComboltems 
GetComboLine GetComboLine 
GetControlID GetControlID 
GetCurrentComboIndex GetCurrentComboIndex 
GetCurrentListIndex GetCurrentListIndex 
GetData GetData 
GetDataStem GetDataStem 
GetDC GetDC 
GetEntryLine GetEntryLine 
getExStyleRaw getExStyleRaw 
GetFocus GetFocus 

getFont getFont 

GetID GetID 

GetItem GetItem 
GetListEntry GetListEntry 
GetListItemHeight GetListItemHeight 
GetListItems GetListItems 
GetListLine GetListLine 
GetListWidth GetListWidth 
GetMenultemState GetMenultemState 
GetMouseCapture GetMouseCapture 
GetMultiList GetMultiList 
GetPixel GetPixel 

GetPos GetPos 
GetRadioButton GetRadioButton 
GetRect GetRect 

GetSBPos GetSBPos 
GetSBRange GetSBRange 
GetSelf GetSelf 
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Item... ... description 
GetSize GetSize 
getStyleRaw getStyleRaw 
getTextSize (deprecated) getTextSize (deprecated) 
getTextSizeDlg getTextSizeDlg 
getTextSizeScreen getTextSizeScreen 
GetValue GetValue 
GetWindowDC GetWindowDC 
GetWindowRect GetWindowRect 
GrayMenultem GrayMenultem 
HandleMessages HandleMessages 





HasKeyPressConnection 


HasKeyPressConnection 





HScrollPos 


HScrollPos 






















































































Help Help 

Hide Hide 

HideFast HideFast 
HidelItem HidelItem 
HideltemFast HideltemFast 
HideWindow HideWindow 
HideWindowFast HideWindowFast 
Init Init 
InitAutoDetection InitAutoDetection 
InitDialog InitDialog 
IsMouseButtonDown IsMouseButtonDown 
Leaving Leaving 
InsertComboEntry InsertComboEntry 
InsertListEntry InsertListEntry 
IsDialogActive IsDialogActive 
isEnabled isEnabled 
IsMaximized IsMaximized 
IsMinimized IsMinimized 

is Visible is Visible 

ItemTitle ItemTitle 
ListAddDirectory ListAddDirectory 
ListDrop ListDrop 
LoadBitmap LoadBitmap 
LogRect2AbsRect LogRect2AbsRect 
Maximize Maximize 
Minimize Minimize 
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Item... ...description 
Move Move 

Moveltem Moveltem 
NoAutoDetection NoAutoDetection 
ObjectToDC ObjectToDC 

OK OK 

OpaqueText OpaqueText 
PeekDialogMessage PeekDialogMessage 
Popup Popup 
PopupAsChild PopupAsChild 
Rectangle Rectangle 

Redraw Redraw 
RedrawClient RedrawClient 
RedrawButton RedrawButton 
RedrawRect RedrawRect 
RedrawWindow RedrawWindow 
RedrawWindowRect RedrawWindowRect 
ReleaseMouseCapture ReleaseMouseCapture 
RemoveBitmap RemoveBitmap 
Resize Resize 

ResizeItem ResizeItem 

Restore Restore 
RestoreCursorShape RestoreCursorShape 
Run Run 

ScreenToClient ScreenToClient 
Scroll Scroll 
ScrollBitmapFromTo ScrollBitmapFromTo 
ScrollButton ScrollButton 
ScrollInButton ScrollInButton 
ScrollText ScrollText 
SendMessageToItem SendMessageToItem 
SetArcDirection SetArcDirection 
SetAttrib SetAttrib 
SetCheckBox SetCheckBox 
SetComboLine SetComboLine 
SetCursorPos SetCursorPos 
SetCurrentComboIndex SetCurrentComboIndex 
SetCurrentListIndex SetCurrentListIndex 
SetData SetData 
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Item... ... description 
SetDataStem SetDataStem 
SetEntryLine SetEntryLine 
SetFocus SetFocus 
SetFocusToWindow SetFocusToWindow 
setFont SetFont 
SetForegroundWindow SetForegroundWindow 
SetGroup SetGroup 
SetHScrollPos SetHScrollPos 
SetVScrollPos SetVScrollPos 
SetItemFont SetItemFont 
SetListColumnWidth SetListColumnWidth 
SetListItemHeight SetListItemHeight 
SetListLine SetListLine 
SetListWidth SetListWidth 
SetListTabulators SetListTabulators 
SetMenultemRadio SetMenultemRadio 
SetMultiList SetMultiList 
SetRadioButton SetRadioButton 
SetRect SetRect 

SetSBPos SetSBPos 
SetSBRange SetSBRange 
SetStaticText SetStaticText 
SetTabStop SetTabStop 
SetTitle SetTitle 

Set Value Set Value 
SetWindowRect SetWindowRect 
SetWindowTitle SetWindowTitle 
Show Show 

ShowFast ShowFast 
ShowItem ShowItem 
ShowItemFast ShowItemFast 
ShowWindow ShowWindow 
ShowWindowFast ShowWindowFast 
Stoplt Stoplt 

TabToNext TabToNext 
TabToPrevious TabToPrevious 





TiledBackgroundBitmap 


TiledBackgroundBitmap 








Title 





Title 
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Item... ... description 
Title= Title= 
TransparentText TransparentText 
ToTheTop ToTheTop 
UncheckMenultem UncheckMenultem 
Update Update 

Validate Validate 
VScrollPos VScrollPos 
Write Write 
WriteDirect WriteDirect 
WriteToButton WriteToButton 
WriteToWindow WriteToWindow 








5.1. Class Methods 


The class methods listed here are class methods of the PlainBaseDialog class. 


5.1.1. setDefaultFont (Class method) 
>>--setDefaultFont (--fontName--,--fontSize--)---------------------------------- >< 


This method changes the default dialog font used for all dialogs. The default dialog font is used 
whenever a dialog template, used in a dynamically defined dialog, does not specify a font. Since it is 
very unusual for a resource script to not specify a font, this mostly effects the PlainUserDialog and 
UserDialog classes. Binary compiled dialog templates (ResDialog) can not be changed, so the default 
dialog font has no meaning for a ResDialog. 


Currently the default font is MS Shell Dlg with a size of 8. MS Shell Dlg is not a true font name, but 
rather a pseudo name that signals the operating system to use a standard font for the specific version of 
Windows. In other words, on Windows 2000, MS Shell Dlg will cause the operating system to use the 
standard font for dialogs on Windows 2000. On XP, the operating system will use the standard XP dialog 
font. (The two fonts are different.) By using this font for the default, ooDialog produces dialogs that 
match what is most common on the current operating system. 


Of course, when the ooDialog programmer specifies a font in either the create() or the createCenter() 
methods then the defualt font is ignored. Once the default font is changed in a process then all dynamic 
dialogs, that don’t specify a font, that are created afterwards will use the new default font. 


The actual font used by a dialog directly effects the value of a dialog unit. 
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Arguments: 


The arguments are: 


fontName 


The family name to use for the default font, for example Tahoma. 


fontSize 


The size of the font, for example, 10. 


Return value: 


This method does not return a value. 


Example: 


This example shows a change to the oostddlg.rex sample program. The default font is changed to 
Tahoma pt 10. This causes all the Standard Dialogs to be created using this font. 


/*®-------------------------------------------------------------------------- */ 
/* */ 
/* OODialog\Samples\oostddlg.rex Standard Dialog demonstration ж/ 
/* */ 
/*®-------------------------------------------------------------------------- */ 


.PlainBaseDialog^setDefaultFont("Tahoma", 10) 
вау 
say ’Starting standard dialog demonstration...’ 


5.1.2. getFontName (Class method) 
>2--ревЕопНаше-------------------------+-+-+-<- нана >< 


Returns Ше current default dialog font name. The default dialog font is used whenever a dialog template, 
used in a dynamically defined dialog, does not specify a font. 


Arguments: 


There are no arguments. 


Return value: 


This method returns the current default font family name. For instance, MS Shell Dlg. 
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Example: 


The following example temporarily changes the default font to run the accounting program. The 
accounting program uses a large number of dynamically defined dialogs. It does not specify the 
dialog font for any of the dialogs. Before starting the program, the default font is changed to 10 pt 
Tahoma. Then, all the dialogs created while the accounting program is executing will be created 
using 10 pt Tahoma. When the accounting program is done, the old default is restored. 


oldName = .PlainBaseDialog^getFontName 
oldSize = .PlainBaseDialog” getFontSize 
.PlainBaseDialog^setDefaultFont("Tahoma", 10) 


ret - excuteAccounting("Daily") 


.PlainBaseDialog^setDefaultFont(oldName, oldSize) 


5.1.3. getFontSize (Class method) 


>2--ревЕопртте-------------+---<+----------+<++<-+-+<+-<- -<--<-<<+ >< 


Returns Ше current default dialog font size. The default dialog font is used whenever a dialog template, 
used in a dynamically defined dialog, does not specify a font. 


Arguments: 
There are no arguments. 


Return value: 


This method returns the current default font size. For instance, 8. 


Example: 


See the previous getFontName() example. 


5.2. Attributes 


This section describes the important attributes of instances of the BaseDialog. (This section of the 
documentation is a work in progress. Please see the attrbutes list at the beginning of this chapeter for 
attributes not listed here.) 


5.2.1. fontName (Attribute) 


>2--тошнаше------- -- - -- ---- - -<- >< 
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>2--ТопНаше--------------------------- --- >< 


Prior to Ше creation of the underlying Windows dialog, Ше font name attribute specifies Ше name of Ше 
font that will be used to create the dialog. This font is only used when the font is not specified in the 
create() or the createCenter() methods. After the creation of the dialog, the attribute reflects the font 
name that was actually used to create the dialog. 


This applies to all dialogs, with this cavaet. With a binary compiled dialog resource (ResDialog) the font 
has always been specified when the dialog template was compiled. Therefore the font name attribute has 
no effect on a ResDialog prior to the execution of the dialog. However, when the ResDialog object is 
executed, the font name attribute is updated to reflect the font used by the dialog. 


Details 


Getting the value of the font name attribute is public: 


name = dlg0bj~ fontName 


Setting the value of the font name attribute is private: 


dlgObj~fontName = "MS Sans Serif" 


will result in an error. 

Set the value of the font name within a method context of the dialog object: 
::class ’MessageBox’ subclass UserDialog 
::method init 


forward class (super) continue 
if self~initCode <> 0 then return 


self~fontName = "MS Sans Serif" 


Note: The font name and font size attributes are set in the super class init() method to the value 
of the default dialog font. Therefore, to have any effect, setting the font name attribute has to be 
done after the super class init() is finished. 
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Example: 


This example is a portion of the code used to to create a message box dialog using a variable font. 
The calcSizes() method is not shown, but in that method the size and position of the controls, and 
the overall size of the dialog, are calculated in relation to the size needed for the message. 


fontName = "Tahoma" 
fontSize = 20 


message = "Drive z: is a network drive and is not accesible." 
title = "Disk Drive Error" 
dlg = .MessageBox^new( , , message, title, fontName, fontSize) 


if dlg^initCode = 0 then до 
dlg^Execute("SHOWTOP", 14) 
end 


dlg^Deinstall 


return 0 
-- End of entry point. 


::requires "oodWin32.cls" 
::class ’MessageBox’ subclass UserDialog inherit AdvancedControls MessageExtensions 


::method init 
expose cx cy message title fontName fontSize 


a = .array^new(2) 
if arg(1, ?E?) then a[1] = arg(1) 
if arg(2, ’E’) then a[2] = arg(2) 


message - arg(3) 

title - arg(4) 

if arg(5, ’E’) then до 
fontName - arg(5) 
fontSize - arg(6) 

end 


forward class (super) arguments (a) continue 
if self^initCode <> 0 then return 


if arg(5, ’E’) then do 
self^fontName - fontName 
self^fontSize - fontSize 
end 


self^calcSizes() 
self~createCenter(cx, cy, title) 


70 ooRexx OODialog Reference Version 4.0.0 


Chapter 5. BaseDialog Class 
5.2.2. fontSize (Attribute) 
»»--fontSize---------------------------------------------------- >< 
>>--їопї81ше=--------------------------------------------------- >< 


Prior to the creation of the underlying Windows dialog, the font size attribute specifies the size of the 
font that will be used to create the dialog. This font is only used when the font is not specified in the 
create() or the createCenter() methods. After the creation of the dialog, the attribute reflects the font size 
that was actually used to create the dialog. 


This applies to all dialogs, with this cavaet. With a binary compiled dialog resource (ResDialog) the font 
has always been specified when the dialog template was compiled. Therefore the font size attribute has 
no effect on a ResDialog prior to the execution of the dialog. However, when the ResDialog object is 
executed, the font size attribute is updated to reflect the font used by the dialog. 


Details 


Getting the value of the font size attribute is public: 


size = dlg0bj~fontSize 


Setting the value of the font size attribute is private: 


dlgObj~fontSize = 8 


will result in an error. 

Set the value of the font name within a method context of the dialog object: 
::class ’MessageBox’ subclass UserDialog 
::method init 


forward class (super) continue 
if self~initCode <> 0 then return 


self~fontSize = 8 


Note: The font name and font size attributes are set in the super class init() method to the value 
of the default dialog font. Therefore, to have any effect, setting the font size attribute has to be 
done after the super class init() is finished. 
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Example: 


See the fontName() example, which also uses the fontSize attribute. 


5.3. Preparing and Running the Dialog 


This section presents the methods used to prepare and initialize a dialog, show it, run it, and stop it. 


5.3.1. Init 


>>-aBaseDialog~ Init (--+--------- за па--не--# ++ gqoep-es--———-- +--)-->< 
+-Library-+ +-,--DlgData.-+ +-,--hFile-+ 


The constructor of the class installs the necessary C functions for the Object Rexx API manager and 
prepares the dialog management for a new dialog. 


Protected: 
This method is protected. You cannot create an instance of BaseDialog. You can only create 
instances of its subclasses. 

Arguments: 


The arguments are: 


Library 


The file name of a .DLL file. Pass an empty string if you do not use binary resources. 


id 
The resource ID, (numeric or symbolic,) of the dialog within the resource file. 

DlgData. 
A stem variable (remember the period!) that contains initialization data for the dialog. For 
example, if you assign the string "Hello world" to DlgData.103, where 103 is the ID of an 
entry field, it is initialized with this string. If the dialog is terminated with OK, the data of the 
dialog is copied into this stem variable. 

hFile 


A file, (often called a header file,) defining symbolic IDs for resources. The symbolic IDs 
defined within the file will be added to the ConstDir directory. 
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Example: 


The following example shows how a header file, symbolic IDs, and the data stem can be used in 
instantiating a new object that is a subclass of the ResDialog. Assume resources.h is a file in the 
same directory as the program file and contains the following: 


/* resources.h */ 
#define IDD_BUILD_DLG 100 
#define IDC_EDITFIELD_INCLUDE 110 
#define IDC_COMBOBOX_PROJECT 120 


#define IDC_RADIO_DEBUG 130 
#define IDC_RADIO_RELEASE 131 
#define IDC_CHECKBOX_CLEAN 140 
#define IDI_DLG_ICON 514 


The dialog (a fictitious build dialog) will have an entry line, a combo box, two radio buttons, and a 
check box. The DlgData. stem will be used to initialize the values of the controls using the 
symbolic IDs defined in the header file. 


/* BuildDlg.rex */ 
DlgData.IDC EDITFIELD. INCLUDE = "C:\sdk\include" 
DlgData.IDC  COMBOBOX PROJECT = "Calculator" 
DlgData.RADIO_DEBUG = 0 
DlgData.RADIO_RELEASE = 1 
DlgData.CHECKBOX_CLEAN = 0 


dlg = .BuildDialog^new( "dlg.dll", IDD_BUILD_DLG, DlgData, "resources.h" ) 
if dlg~initCode <> 0 then до 

say "Error starting dialog.  initCode:" dlg^initCode 

return dlg^initCode 
end 


dlg^execute( "NORMAL", ІРІ DLG ICON ) 


At this point the dialog is shown, the entry line will contain "C:\sdk\include", the combo box will 
have the Calculator project selected, the release radio button will be checked, (the debug radio 
button will not be checked,) and the clean check box will not be checked. 


The user interacts with the dialog and selects ok to close it. Now the state of the dialog when it was 
closed can be determined by checking the DlgData. stem values. 


dlg^deinstall 
if DlgData.CHECKBOX CLEAN == 1 then doClean() 
includePath = DlgData.IDC EDITFIELD. INCLUDE 
if DlgData.RADIO, RELEASE == 1 then 

success = doReleaseBuild(includePath) 


else 
success - doDebugBuild(includePath) 


return success 
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5.3.2. InitAutoDetection 


>>-aBaseDialog” InitAutoDetection------------------------------- >< 


The InitAutoDetection method is called by the Init method to change the default setting for the automatic 
data field detection. 


Automatic data field detection means that for every dialog data item a corresponding Object Rexx 
attribute is created automatically. If you disable automatic detection, you have to use the Connect... 
methods to assign a dialog item to an Object Rexx attribute. 


Protected: 


This method is protected. You can override this method within your subclass to change the standard 
behavior. 


Example: 
The following example overrides the method to switch off auto detection: 


::class MyDialog subclass UserDialog 
::method InitAutoDetection 
self^NoAutoDetection 


5.3.3. NoAutoDetection 


»»-aBaseDialog^NoAutoDetection--------------------------------- >< 


The NoAutoDetection method switches off auto detection. 


5.3.4. AutoDetection 


>>-аВазеПта1ор АшроПефесртоп---------<----------------<<-----<--<-< >> 


The AutoDetection method switches on auto detection. 


5.3.5. InitDialog 


>>-aBaseDialogImitDi alo gasses SS >< 


The InitDialog method is called after the Windows dialog has been created. It is useful for setting data 
fields and initializing combo and list boxes. Do not use Set... methods because the SetData method is 
executed automatically afterwards and sets the values of all dialog items from the attributes. 
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Protected: 


The method is designed to be overwritten in subclasses; it cannot be called from outside the class. 


Example: 
The following example shows how to use InitDialog to initialize dialog items; in this case a list box: 


::class MyDialog subclass Userdialog 

::method InitDialog 
self~InitDialog: super 
AddListEntry(501, "this is the first line") 
AddListEntry(501, "and this one the second") 


5.3.6. Run 


22-aBaseDralog Вш--------- ---------- >< 


The Run method dispatches messages from Ше Windows dialog until the user terminates Ше dialog by 
one of the following actions: 


* Press the OK button (the push button with ID 1) 

* Press the Cancel button (the push button with ID 2) 

* Press the Enter key (if OK or Cancel is the default button) 
* Press the Esc key 


Protected: 


Run is a protected method. You cannot call this method directly; it is called by Execute. 


5.3.7. Execute 


+-DEFAULT--+ 


»»-aBaseDialog^Execute(--"--4---------- таны саа жери +--)---->< 
+-NORMAL---+ +-,--icon-+ 
+-SHOWTOP--+ 
*-HIDE----- * 
+-MIN------ + 
*-MAX------ * 


+-INACTIVE-+ 


The Execute method creates the dialog, shows it (see Show), starts automatic methods, and destroys the 
dialog. The data is passed to the Windows dialog before execution and received from it after the dialog is 
terminated. 


Note: If another dialog has already been started in the same process, it is disabled by Execute. 
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Arguments: 


The arguments are: 


show 
See Show. 
icon 
The resource ID of the dialog’s icon. If an icon ID is not supplied, the default ooDialog icon 


will be used. 


Return value: 


0 
The dialog was not executed. 
1 
You terminated the method using the OK button. 
2 
You terminated the method using the Cancel button. 
Example: 


The following example instantiates a new dialog object (remember that it is not possible to 
instantiate an object of the BaseDialog class), creates a dialog template, and runs the dialog as the 
topmost window. The dialog icon is one of the pre-defined icons supplied by ooDialog: 


MyDialog = .UserDialog^new(...) 
MyDialog^Create(...) 
MyDialog^Execute("SHOWTOP", IDI_DLG_OOREXX) 


5.3.8. ExecuteAsync 


»»-aBaseDialog ExecuteAsync--*-------------- a i a > 
+-(--sleeptime-+ 


| +-DEFAULT--+ | +-,--icon-+ 
+-"--+-NORMAL---+--"-+ 
+-SHOWTOP--+ 
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+-INACTIVE-+ 


The ExecuteAsync method does the same as Execute, except that it dispatches messages asynchronously. 
Therefore the ExecuteAsync method returns immediately after the dialog has been started. 


Arguments: 


The arguments are: 
sleeptime 
The time slice, in milliseconds, until the next message is processed. 


show 
See Show. 
icon 
The resource ID of the dialog’s icon. If an icon ID is not supplied, the default ooDialog icon 


will be used. 


Return value: 


0 
The dialog was started. 
1 
An error occurred. Do not call the EndAsyncExecution method in this case. 
Example: 


The following example starts a dialog and runs the statements between ExecuteAsync and 
EndAsyncExecution asynchronously to the dialog: 


ret = MyDialog^ExecuteAsync(1000, "SHOWTOP") 
if ret = 0 then do 


/* Object Rexx statements to run while the dialog is executing */ 


MyDialog^EndAsyncExecution 
end 
else do 

call errorDialog "Could not start dialog" 
end 
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5.3.9. EndAsyncExecution 


»»-aBaseDialog EndAsyncExecution------------------------------- >< 


The EndAsyncExecution method is used to complete the asynchronous execution of a dialog. It does not 
terminate the dialog but waits until the user terminates it. 


Return value: 


0 
The dialog was not executed. 
1 
The dialog was terminated using the OK button. 
2 
The dialog was terminated using the Cancel button. 
Example: 


See the example in ExecuteAsync. 


5.3.10. Popup 


+-DEFAULT--+ 


»»-aBaseDialog^Popup(--"--4---------- *--'"I-4------------------------------- +--)->< 
+-NORMAL---+ +-,--+----------- +--+--------- +-+ 
+-SHOWTOP--+ +-sleeptime-+ +-,--icon-+ 
+-HIDE----- + 
+-MIN------ + 
*-MAX------ * 


+-INACTIVE-+ 


The Popup method starts a dialog, dispatches messages asynchronously, and returns immediately after 
the dialog is started. 


A dialog started with Popup is independent of any other dialog. This means that a dialog already started 
in the same process is not disabled by Popup. You can therefore use Popup to produce nonmodal dialogs. 


Arguments: 


The arguments are: 


show 


See Show. 
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sleeptime 


The time, in milliseconds, until the next message is processed. 


icon 


The resource ID of the dialog’s icon. If an icon ID is not supplied, the default ooDialog icon 
will be used. 


Return value: 


This method does not return a value. 


Example: 


The following example starts a dialog and runs the statements after Popup asynchronously to the 
dialog. This means that the dialog reacts to an event like pressing a button and calls the connected 
method while the DO loop is being processed: 
MyDialog~Popup("SHOWTOP", 250) 
do i = 1 to 1000 

say "Iteration" i 


call msSleep 100 
end 


This example could also be part of a method handling an event of a dialog, for example dialog A. 
The newly started dialog MyDialog is independent of dialog A. If dialog A is closed, MyDialog 
remains unaffected and active. 


5.3.11. PopupAsChild 


+-DEFAULT--+ 
»»-aBaseDialog^PopupAsChild(--parent--,--"--4---------- qe ? 

*-NORMAL----* 

+-SHOWTOP--+ 


*-HIDE----- * 
*-MIN------ * 
*-MAX------ * 


+-INACTIVE-+ 


>--+------------------------------- 4--)------------------------ >< 
dm, bo +--+- +-+ 


, 


+-sleeptime-+ +-,--icon-+ 


The PopupAsChild method starts a dialog as a child dialog of another dialog, dispatches messages 
asynchronously, and returns immediately after the dialog is started. 


A dialog started with PopupAsChild and its parent dialog can be active at the same time. This means that 
the parent dialog is not disabled by the child dialog. You can therefore use PopupAsChild to produce 
nonmodal dialogs. However, the child dialog is automatically terminated when the parent dialog is 
closed. 
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Arguments: 


The arguments are: 


parent 
An object of the PlainBaseDialog class or one of its descendants that is the parent of the newly 
started dialog. 

show 


See Show. 


sleeptime 


The time, in milliseconds, until the next message is processed. 


icon 


The resource ID of the dialog’s icon. If an icon ID is not supplied, the default ooDialog icon 
will be used. 


Return value: 


This method does not return a value. 


Example: 


The following example starts a dialog and runs the statements after PopupAsChild asynchronously 
to the dialog. This means that the dialog reacts to an event like pressing a button and calls the 
connected method while the DO loop is being processed. The new dialog is started as a child of 
MyParent and is therefore closed when the MyParent dialog is closed: 


MyParent = .UserDialog^new 
MyParent^Popup("SHOWTOP") 


MyDialog^PopupAsChild(MyParent, "SHOWTOP", 250) 
do i = 1 to 1000 

say "Iteration" i 

call msSleep 100 

if i = 800 then MyParent^Finished = 1 /* close both dialogs when i = 800 */ 
end 


This example could also be part of a method handling an event of a dialog, for example dialog A. 
The newly started dialog MyDialog is independent of dialog A. If dialog A is closed, MyDialog 
remains unaffected and active. 


5.3.12. IsDialogActive 


»»-aBaseDialog IsDialogActive---------------------------------- >< 


The IsDialogActive method returns 1 if the Windows dialog still exists. 
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Example: 
The following example tests whether the dialog is active: 


if MyDialog~IsDialogActive then ... 


5.3.13. Stoplt 


2»-aBaseDialog оъора-----------------------<<+ >< 


The StopIt method removes the Windows dialog from the memory. It is called by Execute, after the user 
terminates the dialog. 


Protected: 


This method is protected and for internal use only. 


5.3.14. HandleMessages 


»»-aBaseDialog HandleMessages---------------------------------- >< 


The HandleMessages method handles dialog messages synchronously. It is called by Execute. 
HandleMessages is a dispatcher that receives Windows events and posts the message that is set to handle 
the event. 


5.3.15. AsyncMessageHandling 


»»-aBaseDialog^AsyncMessageHandling(--sleeptime--)------------- >< 


The AsyncMessageHandling method starts the asynchronous handling of dialog messages. It is invoked 
automatically by ExecuteAsync with the Start method of the Object class. A message in this context is 
the name of an object method that is processed whenever the corresponding event occurs. You can set the 
messages that should be sent by using Connect... methods (see page Connect Methods). 


Protected: 
This method is protected and for internal use only. 
Arguments: 


The only argument is: 


sleeptime 


The time slice, in milliseconds, until the next message is processed. 
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5.3.16. PeekDialogMessage 


»»-aBaseDialog^PeekDialogMessage------------------------------- >< 


The PeekDialogMessage method returns the first pending message of the dialog’s message queue 
without removing it from the message queue. 


Return value: 


The first pending message or an empty string. 


5.3.17. ClearMessages 


»»-aBaseDialog^ ClearMessages----------------------------------- >< 


The ClearMessages method clears all pending dialog messages. 


5.3.18. SendMessageToltem 


>>-aBaseDialog~SendMessageToItem(--id-- ,--msg-- ,--wp-- ,--lp--)->< 


The SendMessageTolItem method sends a Windows message to a dialog item. It is used to influence the 
behavior of dialog items. 


Arguments: 
The arguments are: 
id 
The ID of the dialog item. 


msg 


The Windows message (you need a Windows SDK to look up these numbers). 
wp 

The first message parameter (wParam). 

The second message parameter (IParam). 


Example: 
The following example sets the marker to radio button 9001: 


MyDialog^SendMessageToItem(9001, "0х000000Е1", 1, 0) 
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5.4. Connect Event Methods 


The following methods create a connection between an event of the Windows dialog, or a dialog control, 
and a method of the Rexx dialog object. In the Windows user interface, as the user interacts with the 
system, events are generated that specify what the action of the user was. Mouse clicks, keyboard 
presses, moving or sizing windows, all generate events. In the ooDialog framework, when a specific 
event is connected to a method, that method will be invoked each time the event occurs. 


* For push buttons you connect a method to the button. The connected method is called each time the 
button is pressed (clicked.) 


* List boxes, multiple list boxes, and combo boxes can also be connected to a method that is called each 
time a line in the box is selected. 


* Fora scroll bar you can specify different methods that are called depending on the user action. The 
user can click on the arrow buttons, drag the thumb, or use direction keys. 


In a UserDialog the Connect... event methods for buttons are called automatically from the Add... 
methods. However, for most events like the resize or move events, the connection needs to be made 
explicitly. In general, events should be connected before the dialog is shown on the screen. So, the 
Connect... event methods can be used in the InitDialog method. In a UserDialog, the DefineDialog 
method is a good place for the Connect... event methods. If the programmer is overriding the Init 
method, the Connect... event methods can be placed there. But, be sure the methods are not used until 
after the superclass has been initialized. 


Note: The method name that is to be invoked when the specified event occurs must be less than 256 
characters. 


5.4.1. ConnectResize 


»»-aBaseDialog^ConnectResize(--msgToRaise--)------------------- >< 


The ConnectResize method connects a dialog resize event with a method. It is called each time the size 
of the dialog is changed. 


Arguments: 


The only argument is: 


msgToRaise 


The message that is to be sent each time the dialog is resized. Provide a method with a 
matching name. 


Return value: 


This method does not return a value. 
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Example 1: 


dlg = .ResizingDialog^new 
dlg~createCenter(100, 60, "Resize Me", "THICKFRAME") 
dlg~ execute ("SHOWTOP" ) 


::requires ’ooDialog.cls’ 
::class ’ResizingDialog’ subclass UserDialog 


::method init 


forward class (super) continue 
self~connectResize("onSize") 


::method onSize 
use arg sizeEvent, sizeInfo 


-- Wait until the last size event message, in a series of messages, arrives. 
msg = self^peekDialogMessage 
if msg~left(6) = "ONSIZE" then return 


-- sizeInfo contains information about the new width and height in pixels. 
w = .DlgUtil^loWord(sizeinfo) / self~factorX 

h = .DlgUtil^hiWord(sizeinfo) / self~factorY 

say "New width-" w ", new height-" h 


Example 2: 


This example is pulled from the File Viewer example at the end of the "Appearance and Behavior 
Methods" section. А complete working example is presented there that uses a number of the base 
dialog methods. 


::method defineDialog 
expose wasMinimized 


wasMinimized = .false 

style - "VSCROLL HSCROLL MULTILINE READONLY" 
self^addEntryLine(IDC MULTILINE, "cEntry", O, O, 170, 180, style) 
self^connectResize("onSize") 


/* The first arg, sizeEvent, is a flag that the OS sends specifying the type of 
size event. We are only interested in these 3 flags: 


SIZE MINIMIZED 
SIZE MAXIMIZED 
*/ 


::method onSize 


* 
* 
* SIZE RESTORED 
* 
* 


i] 
Ne O 


expose wasMinimized 
use arg sizeEvent sizeInfo 
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if sizeEvent = 1 then wasMinimized = .true 
if sizeEvent = 0 | sizeEvent = 2 then do 
if \ wasMinimized then self~resizeEditControl 


wasMinimized = .false 
end 


Note: Connections are usually placed in the Init or InitDialog method. If both methods are defined, 
use Init as the place for this connection - but not before init:super has been called. 


5.4.2. ConnectMove 


»»-aBaseDialog^ConnectMove(--msgToRaise--)--------------------- >< 


The ConnectMove method connects a dialog move event with a method. It is called each time the 
position of the dialog is changed. 


Arguments: 


The only argument is: 


msgToRaise 


The message that is to be sent each time the dialog is moved. Provide a method with a 
matching name. 


Return value: 
This method does not return a value. 


Example: 


::class MyDlgClass subclass UserDialog 


::method init 
forward class (super) continue 


self^connectMove (onMove) 


::method onMove 
use arg unUsed, posInfo 


-- Look at our message queue to see if the next message in the queue is also 
-- onMove. If so, just return. 

msg = self^peekDialogMessage 

if msg^left(6) = "ONMOVE" then return 
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-- Now, we should be done moving, print out where we are. 
x = .DlgUtil^loWord(posInfo) 


y = .DlgUtil^hiWord(posInfo) 
say "At coordinate (’ x’,’ y? ) on the screen. (In pixels.) 


Note: Connections are usually placed in the Init or InitDialog method. If both methods are defined, 
use Init as the place for this connection - but not before init:super has been called. 


5.4.3. ConnectPosChanged 


»»-aBaseDialog^ConnectPosChanged(--msgToRaise--)--------------- >< 


The ConnectPosChanged method connects a change regarding the dialog coordinates with a method. It is 
called each time the size, position, or place in the Z order of the dialog is changed. 


Arguments: 


The only argument is: 


msgToRaise 


The message that is to be sent each time the coordinates of the dialog are changed. Provide a 


method with a matching name. 


Return value: 


This method does not return a value. 


Example: 


::class MyDlgClass subclass UserDialog 
::method Init 
self~init:super(...) 


self^ConnectPosChanged("OnNewPos") 


::method OnNewPos 
say "The new rectangle is" self~GetWindowRect (self^DlgHandle) 


Note: Connections are usually placed in the Init or InitDialog method. If both methods are defined, 
use Init as the place for this connection - but not before init:super has been called. 
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5.4.4. ConnectMouseCapture 


>>-aBaseDialog~ ConnectMouseCapture (--msgToRaise--) ------------- >> 


The ConnectMouseCapture method connects a method with the lose-mouse-capture event. It is called 
each time the dialog loses the mouse capture. This can happen, for example, when you move a dialog 
with the mouse and release the left mouse button. 


Arguments: 


The only argument is: 


msgToRaise 


The message that is to be sent each time the mouse capture is lost in the dialog. Provide a 
method with a matching name. 


Return value: 


This method does not return a value. 


5.4.5. ConnectHelp 


»»-aBaseDialog^ConnectHelp(--msgToRaise--)----------------------- >< 


The ConnectHelp method connects Ше Windows Help event with a method in the dialog class. The 
Windows Help event occurs when the user presses the Е1 key. (Only the Help events generated when the 
dialog is the active window are connected.) 


Arguments: 


The only argument is: 


msgToRaise 


The name of the method that is to be invoked. 


Return value: 


No error. 


An (internal) error prevented the message from being connected to a method. 
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Event Method Arguments 


The ooDialog method connected to the Help event will receive the following four arguments in the 
order listed: 


id 
The resource ID of the dialog, dialog control, or menu item that had the focus when the F1 key 
was pressed. 


type 


Specifies if the ID in argument 1 was from a window (a dialog or dialog control) or from a 
menu item. This argument will either be WINDOW or MENU. 


mouseX 


The x coordinate of the mouse at the time the F1 key was pressed. This value is an absolute 
screen coordinate (pixel) and note that the mouse will not necessarily be over the dialog. 


mouseY 


The y coordinate of the mouse at the time the F1 key was pressed. 


Example: 


::method Init 
self~init:super 


self^connectResize(onResize) 
self^connectHelp(onHelp) 


::method onHelp 
use arg id, type, mouseX, mouseY 
if type == "MENU" then и = ’Menu id’ id; else и = "Dialog id’ id 
say "Help request:" 
ѕау " "w 
say " Mouse position x:" mouseX "y:" mouseY 


/* As the user presses the F1 key at various times when the dialog has the focus 
* the output might be as follows: 
*/ 


Help request: 

Dialog id 12 

Mouse position x: 420 y: 106 
Help request: 

Menu id 60 

Mouse position x: 204 y: 93 





Help request: 
Menu id 65 
Mouse position x: 203 y: 166 
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Help request: 

Dialog id 14 

Mouse position x: 218 y: 410 
Help request: 

Dialog id 80 

Mouse position x: 387 y: 462 


5.4.6. ConnectKeyPress 


>>-aBaseDialog~ConnectKeyPress (--msgToRaise-- ,--keys-+------------ +--)---->< 
+=, -Sfilter==+ 


The ConnectKeyPress method connects a key press event with a method in the dialog class. A single key 
or multiple keys can be connected to the same method. Multiple methods can be connected for key press 
events, but only 1 method can be connected to any single key. 


The underlying Windows dialog must exist before this method can be used. That means it can be used in 
InitDialog or any time thereafter. There is a maximum limit of 63 methods, per dialog, that can be 
connected to key press events. Connections can be removed (see the DisconnectKeyPress method) if 
there is no longer a need for a notification of a key press. 


A similar method is a member of the DialogControl class. It is important to note this distinction 
between the two methods. The method of the BaseDialog (this method) will capture any key press event 
when the dialog is the active window. The method of the DialogControl class will only capture a key 
press when the control has the keyboard focus. 


Arguments: 


The arguments are: 


msgToRaise 


The name of the method that is to be invoked when the key press event happens. 


keys 


The key (or keys) for which the key press event is to be connected. A single key or multiple 
keys can be specified. A range of keys can be used. Each single key or range of keys is 
separated by a comma. A range of keyes is denoted by using the dash character "-". White 
space within the keys argument is ignored. 


The keys are specified by the numeric value defined by Microsoft for its virtual key set. These 
numeric values are 0 through 255, although both 0 and 255 are not used. The VirtualKeyCodes 
class can be used to make a program more readable. 


Note: The programmer can use the Windows documentation and Platform SDK to obtain the 
full list of the virtual key numbers. 


In addition there are a few keywords that can be used to specify some common key ranges. 
These keywords are: 
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ALL 
All keys. 


FKEYS 


All Function keys, other than F1. (In Windows the F1 key is the help key and the 
ConnectHelp method should be used for F1.) 


ALPHA 
The keys A though Z. 


NUMERIC 


The keys 0 through 9. Note that these are the normal number keys, not the keypad 
numbers on an enhanced keyboard. 


ALPHANUMERIC 
The keys A through Z and 0 through 9. 


Note: Case is insignificant for these keywords as is the order of the keywords. A keyword not in 
the list will result in a return of -1. However, if the argument contains other valid key tokens, 
those keys will be connected to the method. If there are no other valid key tokens, then no 
connection is made. 


filter 


A (simplistic) filter that is applied to the key press event for the key(s) specified. The filter is a 
string of keywords separated by blanks. (Case is not significant, neither is the order of the 
words. Any words other than the specified keywords are ignored.) The possible keywords are: 
SHIFT, CONTROL, ALT, AND, NONE. 


Shift, control, and alt specify that the corresponding key must be down at the time of the key 
press event. These keywords are combined in a boolean expression. The default is an OR 
expression. If the AND keyword is present then the boolean expression is an AND expression. 
If the NONE keyword is used, it means that none of the shift, control, or alt keys can be down 
at the time of the key press event. (When NONE is used, all other words in the string are 
ignored.) 


Some examples may make this more clear: 
::method initDialog 
-- Using the below, the onAltCD method would be invoked when the user types 


-- Alt-Shift-C or Alt-Shift-D. But the method would not be invoked for Alt-C 
-- or Shift-D (or any other key press event.) 


keys = self^vCode(C C?) "," self~vCode(’D’) 
self^connectKeyPress(onAltCD, keys, "ALT AND SHIFT") 
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-- The below would invoke the onAltCD method any time a C or a D was typed 
-- with either the Alt or the Control key down. This would include Alt-C, 
-- Alt-Shift-C, Ctrl-Alt-Shift-C, etc.. 

self^connectKeyPress(onAltCD, keys, "ALT CONTROL") 


-- The below would invoke the onAltCD method only when Alt-C or Alt-D was 
-- typed. 


self^connectKeyPress(onAltCD, keys, "ALT AND") 


-- The below would invoke the onF4 method only when the F4 key was pressed by 
-- itself. Alt-F4, Ctrl-F4, etc., would not invoke the method. 


self^connectKeyPress(onF4, self~vCode(’F4’), "NONE") 


Return value: 


The return values are: 


0 
Success. 
-1 
A problem with one of the arguments, such as skipping a required argument, using an incorrect 
format for the keys or the filter arguments, etc.. Note that it is possible to get a return of -1 
but still have some keys connected. For instance in the following example the C and D keys 
would be connected and the filter applied. The ""dog"" token would result in -1 being returned: 
keys = self~vCode(’C’) ", dog," self~vCode(’D’) 
ret = self^connectKeyPress("onAltCD?, keys, "ALT AND SHIFT") 
say ’Got a return of:’ ret 
say "Have connection to onAltCD?" self^hasKeyPressConnection(?onAltCD?) 
-- The output would be: 
Got a return of: -1 
Have connection to onAltCD? 1 
-2 
The underlying mechanism in the Windows API that is used to capture key events failed. 
-4 
An (internal) problem with the dialog window. 
-5 
Memory allocation error in the underlying Windows API. 
-6 


The maximum number of connections has been reached. 
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7 


The msgToRaise method is already connected to a key down event for this dialog. 


Event Method Arguments 


The ooDialog method connected to the key press event will receive the following five arguments in 
the order listed: 


keyCode 


The numeric code of the key pressed. 


shift 


A boolean (true or false) that denotes whether a shift key was down or up at the time of the key 
press. It will be true if a shift key was down and false if the shift key was not down. 


control 


True if a control key was down at the time of the key press, false if it was not. 


alt 


True if an alt key was down at the time of the key press, false if it was not. 


extraInfo 


This argument is a string containing keywords. It supplies extra information about the 
keyboard state at the time of a key press event. The string will contain some combination of 
these keywords 


numOn 


Num Lock was on at the time of the key press event. 


numOff 


Num Lock was off. 


capsOn 


Caps Lock was on at the time of the key press event. 


capsOff 
Caps Lock was off. 


scrollOn 


Scroll Lock was on at the time of the key press event. 


scrollOff 
Scroll Lock was off. 
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IShift 


The left shift key was down at the time of the key press event. 


rShift 
The right shift key was down. 


IControl 


The left control key was down at the time of the key press event. 


rControl 


The right control key was down. 


ІАЕ 


The left alt key was down at the time of the key press event. 


rAlt 
The right alt key was down. 


Example: 


The following example is from a fictitious customer order system. As the user is filling out a 
customer order using the customer order dialog, he has the F2 through F5 short cut keys available. 
F2 brings up a customer look up dialog. F3 looks up info on the product number entered in an edit 
control. F4 resets the form by clearing all the fields. F5 is used to print out the finished invoice. 


::method initDialog 


-- Capture F2 key presses, but not Ctrl-F2 or А1+-Е2, etc.. 
self~connectKeyPress(onF2, self~vCode(’F2’), "NONE") 


-- Same idea for F3, F4, and F5. This uses the actual numeric value for the 
-- keys without bothering to use the VirtualKeyCodes class to translate. 
self~connectKeyPress(onF3, 114, "NONE") 

self~connectKeyPress(onF4, 115, "NONE") 

self~connectKeyPress(onF5, 116, "NONE") 


::method onF2 
ве! Е” showCustomerLookupDialog 


::method onF3 


prodNum = self~getEditControl (IDC_EDIT_PRODUCT) ^getText 
if prodNum \== "" then self^showProductInfo(prodNum) 


::method onF4 
self^resetAllFields 
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::method onF5 
self^printInvoice 


5.4.7. ConnectFKeyPress 


»»-aDialogControl^ConnectFKeyPress(--msgToRaise--)------------- >< 


The ConnectFKeyPress method connects a function key press to a method in the dialog instance. This 
works for function keys F2 through F24, without the shift, control, or alt keys also being pressed. The 
underlying Windows dialog must exist before this method can be invoked. This is a convenience method 
and is exactly equivalent to: 


::method initDialog 


keys = self~vCode(’F2’) "-" self~vCode(’F24’) 
self~connectKeyPress(msgToRaise, keys, "NONE") 


Arguments: 


The required argument is: 


msgToRaise 


The method to be invoked for the F key press event. 


Return value: 


The return values are: 


0 
Success. 
-2 
The underlying mechanism in Ше Windows API that is used to capture key events failed. 
-4 
An (internal) problem with the dialog window. 
-5 
Memory allocation error in the underlying Windows API. 
-6 


The maximum number of connections has been reached. 
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The msgToRaise method is already connected to a key down event for this dialog. 


Example: 


The following example is a variation on the example shown for the ConnectKeyPress method. It 
connects all the function keys to the same method and then determines what action to take by 
examining which key was pressed. 


::method initDialog 


-- Capture all function key presses. 
self~connectFKeyPress (опЕКеу) 


::method onFKey 
use arg keyPressed 


select 
when self^keyName(keyPressed) == ’F2’ then self^showCustomerLookupDialog 


when keyPressed - 114 then do 
prodNum - self^getEditControl(IDC, EDIT. PRODUCT) ^getText 
if prodNum \== "" then self^showProductInfo(prodNum) 
end 


115 then self^resetAllFields 
when keyPressed - 116 then self^printInvoice 


when keyPressed 


otherwise do 
-- Not interested in any other function keys 
nop 
end 
end 


5.4.8. DisconnectKeyPress 


»»-aBaseDialog^DisconnectKeyPress(--4-------------- +--)-------- >< 
+--methodName--+ 


The DisconnectKeyPress method disconnects a key press event from a method that was previously 
connected using ConnectKeyPress. If no method name is specified than all key press event connections 
are removed. Otherwise, only the key press events connected to the specific method are removed. 
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Arguments: 


The single optional argument is: 


methodName 


If methodName is specified, only the key press events connected to that method are 
disconnected. If the argument is omitted, then all key press events for the dialog will be 
disconnected. 


Return value: 


The return values are: 


0 
Success. 

-1 
The specified methodName is not connected to any key press events for this dialog. 

-2 
This return code can only occur when removing the connection for a single methodName. It 
indicates that after removing the connection, the underlying mechanism in the Windows API 
that captures the key press events could not be re-initialized. (It is doubtful this error would 
ever occur.) 

Example: 


The following example is a variation on the example shown for the ConnectKeyPress method. It 
builds on the fictitious customer order system. The F7 key saves the completed invoice into the 
system and enters a different phase of the companies business process. At this point (for whatever 
fictitious business reason) the fields can no longer be cleared and the user is not allowed to look up 
customer or product information. But, the user may still need to print the invoice. To prevent the 
accidental press of the hot keys causing the wrong action, those key presses are disconnected. 


To demonstrate how key press connections can be added and removed through out the live time of 
the dialog, this example adds the F9 hot key. F9 starts a new order entry cycle and re-connects the 
hot keys used during the creation of a customer invoice. When the user then saves the next 
completed invoice, key press connections are removed, when she starts a new invoice key press 
connections are restored. This cycle could continue though out the day without the user ever closing 
the main dialog. 


::method initDialog 


-- Capture F2 key presses, but not Ctrl-F2 or Alt-F2, etc.. 
self^connectKeyPress(onF2, self~vCode(’F2’), "NONE") 


-- Same idea for F3, F4, F5, and F7. This uses the actual numeric value for 
-- the keys without bothering to use the VirtualKeyCodes class to translate. 
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::method onF2 
self^showCustomerLookupDialog 


::method onF3 
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prodNum - self^getEditControl(IDC EDIT PRODUCT) ^getText 
if prodNum \== "" then self^showProductInfo(prodNum) 


::method onF4 
self^resetAllFields 


::method onF5 
self^printInvoice 


::method onF7 


self^saveToDataBase 

self~disconnectKeyPress (onF2) 
self~disconnectKeyPress (onF3) 
self~disconnectKeyPress (onF4) 


::method onF9 


self^resetAllFields 

self^connectKeyPress(onF2, 112, 
self^connectKeyPress(onF3, 114, 
self~connectKeyPress(onF4, 115, 


"NONE") 
"NONE") 
"NONE") 


5.4.9. HasKeyPressConnection 


»»-aBaseDialog^HasKeyPressConnection(--4-------------- * 
*--methodName---* 


--)-------- >< 


This method is used to query if a connection to a key press event already exists. It returns true or false so 
it can always be used in a boolean expression. If no argument is specified the method returns true if any 
key press events have been connected for the dialog and false otherwise. When the methodName argument 
is used, the query is only if there are key press events connected to the specified method. 
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Arguments: 


The single optional argument is: 


methodName 


Query if any key press events are connected to this method. 


Return value: 


The returned value is always true or false. 
true 

A connection exists. 
false 


No connection exists. 


Example: 


The following example could come from a dialog where the user has the option to use hot keys or 
not. When the reset button is pushed the state of the dialog fields are reset. The hot keys enabled 
check box is set to reflect whether hot keys are currently enabled or not. 


::method defineDialog 


self^addCheckBox(IDC CHECK FKEYSENABIED, , 30, 60, , , "Hot Keys Enabled") 


self^addButton(IDC PB RESET, 60, 135, 45, 15, "Reset", onReset) 
::method onReset 


if self^hasKeyPressConnection then 
self^getCheckControl(IDC, CHECK, FKEYSENABIED) ~check 
else 
self^getCheckControl(IDC, CHECK, FKEYSENABIED) “uncheck 


5.4.10. ConnectButton 


»»-aBaseDialog^ConnectButton(--id--,--msgToRaise--)------------ >< 


The ConnectButton method connects a push button with a method. 
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Arguments: 


The arguments are: 
id 
The ID of the dialog element. 


msgToRaise 
The message that is sent each time the button is clicked. You must provide a method with a 


matching name. 


Return value: 


-1 
The specified symbolic ID could not be resolved. 
0 
No error. 
Example: 


::class MyDlgClass subclass UserDialog 


::method Init 
self~init:super(...) 
self~ConnectButton(203, "SayHello") 


::method SayHello 
say "Hello" 


Note: Connections are usually placed in the Init or InitDialog method. If both methods are defined, 
use Init as the place for this connection - but not before init:super has been called. 


5.4.11. ConnectBitmapButton 


»»-aBaseDialog^ConnectBitmapButton(--id--,--4------------ +--,--bmpNormal--> 
+-msgToRaise-+ 


"zr E +--)->< 


+= ==БарЕосивва=-=+=============3=8=========ыенеБе=ененен=вејенын=ыееененные +=+ 
#-- ,--Бироейесъед-+---------------------<-< + +-+ 
*-,--bmpDisabled--4----------------- +-+ 
+-,--styleOptions-+ 
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The ConnectBitmapButton method connects a bitmap and a method with a push button. The given 
bitmaps are displayed instead of a Windows push button. 


Arguments: 


The arguments are: 


id 
The ID of the button. 

msgToRaise 
The message that is to be sent to this object when the button is clicked. 

bmpNormal 
The name (alphanumeric), resource ID (numeric), ог handle (J/NMEMORY option) of a bitmap 
file. This bitmap is displayed when the button is not selected, not focused, and not disabled. It 
is used for the other button states in case the other arguments are omitted. 

bmpFocused 
This bitmap is displayed when the button is focused. The focused button is activated when the 
Enter key is pressed. 

bmpSelected 
This bitmap is displayed while the button is clicked and held. 

bmpDisabled 
This bitmap is displayed when the button is disabled. 

styleOptions 


One of the following keywords: 


FRAME 
Draws a frame around the button. When using this option, the bitmap button behaves like 
a normal Windows button, except that a bitmap is shown instead of a text. 

USEPAL 


Stores the colors of the bitmap file as the system color palette. This option is needed when 
the bitmap was created with a palette other than the default Windows color palette. Use it 
for one button only, because only one color palette can be active at any time. USEPAL is 
invalid for a bitmap loaded from a DLL. 
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INMEMORY 


This option must be used if the named bitmaps are already loaded into memory by using 
the LoadBitmap method. In this case, bnpNormal, bmpFocused, bmpSelected, and 
bmpDisabled specify a bitmap handle instead of a file. 


STRETCH 


If this option is specified and the extent of the bitmap is smaller than the extent of the 
button rectangle, the bitmap is adapted to match the extent of the button. STRETCH has 
no effect for bitmaps loaded through a DLL. 


Return value: 


-1 
The specified symbolic ID could not be resolved. 
0 
No error. 
Example: 


The following example connects a button with four bitmaps and a method: 


::method InitDialog 
self~ConnectBitmapButton(204, "BmpButtonClicked", , 
"AddBut_n.bmp", "AddBut_f.bmp", , 
"AddBut s.bmp", "AddBut_d.bmp", "FRAME") 
::method BmpButtonClicked 


See also method ChangeBitmapButton. 


5.4.12. ConnectControl 


»»-aBaseDialog^ConnectControl(--id--4--------------- +--)------- >< 
*-,--msgToRaise-* 


The ConnectControl method connects a dialog control with a method. 
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Arguments: 


The arguments are: 


id 
The ID of the dialog element. 


msgToRaise 


The message that is to be sent each time the button is clicked. Provide a method with the 
matching name. 


Return value: 


The specified symbolic ID could not be resolved. 


No error. 


5.4.13. ConnectDraw 


>>-aBaseDialog~ ConnectDraw-- (--id--4--------------- +--)-------- >< 
+-,--msgToRaise-+ 


The ConnectDraw method connects the WM_DRAWITEM event with a method. A WM_DRAWITEM 
message is sent for owner-drawn buttons each time they are to be redrawn. 


Arguments: 


The arguments are: 


id 
The ID of the dialog control. If the ID is omitted, all drawing events of all owner-drawn 
buttons are routed to the method. 

msgToRaise 


The message that is to be sent each time the WM_DRAWITEM event occurs. Provide a 
method with the matching name. You can use USE ARG ID to retrieve the ID of the item that is 
to be redrawn. 
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Return value: 


The specified symbolic ID could not be resolved. 


No error. 


5.4.14. ConnectList 


>>-aBaseDialog~ConnectList (--id--+--------------- 4--)---------- >< 
*-,--msgToRaise-* 


The ConnectList method connects a list box, multiple list box, or combo box with a method. The method 
is called each time the user selects a new item from the list. 


Arguments: 


The arguments are: 


id 
The ID of the dialog element. 


msgToRaise 


The message that is to be sent each time the button is pressed. Provide a method with the 
matching name. 


Return value: 


The specified symbolic ID could not be resolved. 


No error. 


5.4.15. ConnectListLeftDoubleClick 


>>-aBaseDialog~ ConnectListLeftDoubleClick(--id-- ,--msgToRaise--)->< 
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The ConnectListLeftDoubleClick method combines a left double-click within the list box with a method. 


Arguments: 


The arguments are: 


id 
The ID of the list box. 


msgToRaise 


The name of the method that is to be called. 


Return value: 


The specified symbolic ID could not be resolved. 


No error. 


5.4.16. ConnectScrollBar 


>>-aBaseDialog~ ConnectScrollBar (--id-- ,--msgWhenUp-- , --msgWhenDown--> 


>--+-------------------------------------------------------------------- +--> 
+-,--+------------- +--+-------------------------------------------- +-+ 
+-msgWhenDrag-+ +-,--+----- Harboe SSR tae ese з= ш +-+ 
+-min-+ +-,--+----- +--+------------ +-+ 
+-шах-+ +-,--+-----+-+ 
+-роѕ-+ 
>--+---------------------------------------------------------- +--> 
+-,--+---------- +--+------------------------------------- +-+ 
+-progpgup-+ +-,--+---------- +--+---------------- +-+ 
+-progpgdn-+ +-,--+--------- +-+ 
+-ргоріор-+ 
>--+------------------- +--+------------------------------------+-- > 
+-,--+------------ +-+ о +-,--+----------- +--+-------------- +-+ 
+-progbuttom-+ +-progtrack-+ +-,--progendsc-+ 
»--)----------------------------------------------------------- >< 
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The ConnectScrollBar method initializes and connects a scroll bar to an Object Rexx object. Use this 
method in the InitDialog method. 


Protected: 
This method is protected. 
Arguments: 
The arguments are: 
id 
The ID of the scroll bar. 


msgWhenUp 


The method that is called each time the scroll bar is incremented. 


msgWhenDown 


The method that is called each time the scroll bar is decremented. 


msg WhenDrag 


The method that is called each time the scroll bar is dragged with the mouse. 


min, max 


The minimum and maximum values for the scroll bar. 


pos 


The current or preselected value. 


progpgup 
The method that is called each time the scroll bar is focused and the PgUp key is pressed. 


progpgdn 
The method that is called each time the scroll bar is focused and the PgDn key is pressed. 


progtop 


The method that is called each time the scroll bar is focused and the Home key is pressed. 


progbottom 


The method that is called each time the scroll bar is focused and the End key is pressed. 


progtrack 


The method that is called each time the scroll box is dragged. 


progendsc 


The method that is called each time the scroll box is released after the dragging. 
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Return value: 


-1 
The specified symbolic ID could not be resolved. 
0 
No error. 
Example: 


In the following example, scroll bar 255 is connected to three methods and initialized with 1 as the 
minimum, 20 as the maximum, and 6 as the current value: 


::class MyDialog subclass UserDialog 


::method DefineDialog 
self~ConnectScrollBar (255, "Іпсгеаѕе", "Decrease", "Drag",1,20,6) 


::method Increase 


::method Decrease 


::method Drag 


/* see CombineElWithSB below for continuation */ 


5.4.17. ConnectAllSBEvents 


»»-aBaseDialog^ConnectAllSBEvents(--id--,--Prog----------------- ? 
»--—---------------------------------------- 4--)--------------- >< 
+-,--+----- +--+------------------------ +-+ 
*-min-* +-,--+-----+--+--------+-+ 
+-шах-+ +-,--pos-+ 


Connects all scroll bar events to one method. 
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Protected: 


This method is protected. 
Arguments: 
The arguments are: 
id 
The ID of the scroll bar 


Prog 


The method that is called for all events sent by the scroll bar. 


min, max 
The minimum and maximum values for the scroll bar. 
pos 


The current or preselected value. 


Return value: 


The specified symbolic ID could not be resolved. 


No error. 


5.4.18. addUserMsg 


»»-aBaseDialog^addUserMsg(--msgToRaise--,--msgWindows----------- ? 
B-—R-------------------------------------------------------------------- +--> 
ро Ol ра ар +-+ 
+ --пРагаш--+----- ш шз шышы шышы ш н шш =н +-+ 

a SET h A -- +-+ 
+-,--lParam--+---------- +-+ 


+-,--filt3-+ 


»--)----------------------------------------------------------- >< 


The addUserMsg method connects a Windows message with an Object Rexx method. This method is 
designed to be used by ooDialog programmers who are familiar with the Windows API. 
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You have to pass the Windows message ID and the two message parameters (wParam and lParam) to 
specify the exact event you want to catch. In addition, you can specify filters for each parameter. Filters 
are useful for catching more than one message or one parameter with one method. 


Details for all Windows messages and their parameters are available in the Windows documentation. The 
numeric value of the message IDs (and possibly the message parameters) can be looked up in the 
Windows platform SDK. 


Protected: 
This method is protected. You can use it only within the scope of the BaseDialog class or its 
subclasses. 

Arguments: 


The arguments are: 


msgToRaise 


The message that is to be sent to the Object Rexx dialog object each time the specified 
Windows message is caught. Provide a method with the same name. The maximum size for a 
message is limited to 256 characters. 


msgWindows 


The message in the Windows environment that is to be caught. 


filtl 


This filter is used to binary AND the incoming Windows message. 


wParam 


This is the first parameter that must be passed with the Windows message. 


filt2 


This filter is used to binary AND the wParam argument. 


ІРагат 


This is the second message parameter. 
filt3 


This is the filter for lParam. 


Example: 
The following example shows an implementation of the ConnectList method: 


::class BaseDialog 


::method ConnectList 
use arg msgToRaise, id 
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self~addUserMsg(msgToRaise, "0x00000111", "OxFFFFFFFF", , 
"0х0001" | |14742х(4), "OxFFFFFFFF", 0, 0) 


Assume that this method is called with ID=254 апа msgToRaise="ListChanged". After the 
ConnectList is executed, the ListChanged message is sent to the Object Rexx dialog object if the 
following conditions are true: 


* Message "0x00000111" (WM. COMMAND) is generated by Windows in answer to an event (for 
example, a button is clicked or a list has changed). The filter "OxFFFFFFFF" ensures that only 
that message is caught; if the filter were "ОХЕЕЕЕЕЕЕЕ", the message "0x00001111" would be 
caught as well. 


* The first message parameter is "0x000100FF". The first part, "0x0001", specifies the event, and 
the second рап, "OxOOFE" (equals decimal 254), specifies the dialog control where the event 
occurred. By using another filter it is possible to make more than one event a trigger for the 
ListChanged method; for example, filter "OxFFFFFFFE" would ignore the last bit of the ID, and 
this the same event for dialog item 255 would call ListChanged as well. 


* The second message parameter and its filter are ignored. 


The following example invokes a user-defined method DoubleClick each time the left mouse button 
is double-clicked: 


self^addUserMsg("DoubleCick","0x00000203","OxFFFFFFFF",0,0,0,0) 


5.5. Connect Attribute Methods 


The following methods create a connection between a dialog control and an attribute of the dialog object. 
The attribute is used to reflect the value associated with the dialog control. For instance the text of an edit 
control. 


* For data items, such as an entry line, list box, or combo box, an attribute is created and added to the 
dialog object. The attribute is used as an interface to the data of the entry line, list box, or combo box. 


* Check boxes and radio buttons are also data items and are therefore connected to an attribute. The only 
valid values for these attributes are | for selected and 0 for not selected. 


In a UserDialog the Connect... attribute methods are called automatically from the Add... methods. The 
proper place for Connect... attribute methods is the InitDialog method. 


5.5.1. ConnectEntryLine 


»»-aBaseDialog^ConnectEntryLine(--id--4------------------ +--)-->< 
+-,--attributeName-+ 


The ConnectEntryLine method creates a new attribute and connects it to the entry line id. The attribute 
has to be synchronized with the entry line manually. This can be done globally with the SetData and 
GetData methods (see page GetData), or for only one item with the SetEntryLine and GetEntryLine 
methods (see page GetEntryLine). It is done automatically by Execute when the dialog starts and after it 
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terminates. If AutoDetection is enabled, or if the dialog is created dynamically (manually or based on a 
resource script), you do not have to use this method or any other Connect... methods that deal with dialog 
controls). 


Arguments: 


The arguments are: 
id 
The ID of the entry field you want to connect. 


attributeName 


An unused valid Rexx symbol because an attribute with exactly this name is added to the 
dialog object with this method. Blank spaces, ampersands (&), and colons (:) are removed 
from the attributeName. If this argument is omitted, is not valid, or already exists, and the ID is 
numeric, an attribute with the name DATAid is used, where id is the value of the first argument. 


Return value: 


-1 
The specified symbolic ID could not be resolved. 
0 
No error. 
Example: 


In the following example, the entry line with ID 202 is associated with the attribute Name. "Put 
your name here!" is assigned to the newly created attribute. Then the dialog is executed. After the 
dialog has terminated, the data of the entry line, which the user might have changed, is copied back 
to the attribute Name. 


MyDialog~ConnectEntryLine (202, "Name") 
MyDialog^Name-"Put your name here!" 
MyDialog^Execute("SHOWTOP") 

say MyDialog~Name 


5.5.2. connectComboBox 
»»-aBaseDialog^connectComboBox(--id--4------------------------------------- +==> 
+-,--+--------------- +--+----------- +-+ 


+-attributeName-+ +-,--"LIST"-+ 


»--)----------------------------------------------------------- >< 
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The connectComboBox method creates an attribute and connects it to a combo box. The value of the 
combo box, that is, the text in the entry line or the selected list item, is associated with this attribute. See 
ConnectEntryLine for a more detailed description. 


If the combo box is of type "Drop down list", you must specify "LIST" to connect an attribute with the 
combo box. 


Return value: 


The specified symbolic ID could not be resolved. 


No error. 


5.5.3. ConnectCheckBox 


»»-aBaseDialog^ConnectCheckBox(--id--4------------------ +--)--->< 
+-,--attributeName-+ 


The ConnectCheckBox method connects a check box control to a newly created attribute. A check box 
attribute has only two valid values: | if the box has a check mark, and 0 if it has not. See 
ConnectEntryLine for a more detailed description. 


Return value: 


The specified symbolic ID could not be resolved. 


No error. 


5.5.4. ConnectRadioButton 


»»-aBaseDialog^ConnectRadioButton(--id--4------------------ decem» 
+-,--attributeName-+ 


»--)----------------------------------------------------------- >< 
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The ConnectRadioButton method connects a radio button control to a newly created attribute. A radio 
button attribute has only two valid values: 1 if the radio button is marked and 0 if it is not. See 
ConnectEntryLine for a more detailed description. 


Return value: 


The specified symbolic ID could not be resolved. 


No error. 


5.5.5. ConnectListBox 


»»-aBaseDialog^ConnectListBox(--id--4------------------ +--)---->< 
+-,--attributeName-+ 


The ConnectListBox method connects a list box to a newly created attribute. The value of the attribute is 
the number of the selected line. Therefore, if the attribute value is 3, the third line is currently selected or 
will be selected, depending on whether you set data to the dialog or receive it. See ConnectEntryLine for 
a more detailed description. 


Return value: 


The specified symbolic ID could not be resolved. 


No error. 


5.5.6. ConnectMultiListBox 


»»-aBaseDialog^ConnectMultiListBox(--id--4------------------ +===> 
+-,--attributeName-+ 


>) ннн >< 


The ConnectMultiListBox method connects а list box to а newly created attribute. The list box has ће 
multiple-selection style enabled (by setting the MULTI option when adding this list box), that is, you can 
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select more than one item at the same time. The value of the attribute is a string containing the numbers 
of the selected lines. The numbers are separated by blank spaces. Therefore, if the attribute value is 3 5 6, 
the third, fifth, and sixth item are currently selected, or will be selected if SetData is executed. See 
ConnectEntryLine for a more detailed description. 


Return value: 


-1 
The specified symbolic ID could not be resolved. 
0 
Мо еггог. 
Example: 


The following example defines a list box with the name of the four seasons. It then preselects the 
items Summer and Winter. After execution of the dialog, it parses the value of the attribute. 


MyDialog = .ResDialog^new(...) 
MyDialog^NoAutoDetection 
MyDialog^addListBox(205, ..., "MULTI") 
MyDialog^ConnectMultiListBox(205, "ListBox") 
seasons .1="Spring" 
seasons .2=" Summer" 
seasons .3=" Autumn" 
seasons.4-"Winter" 
do season over seasons 
MyDialog^AddListEntry(205, season) 
end 
MyDialog^ListBox-"2 4" 
MyDialog^Execute("SHOWTOP") 
selltems = MyDialog~ListBox 
do until anItem ="" 
parse var selltems anItem selltems 
say "You selected: "seasons.anItem 
end 


5.5.7. AddAttribute 


»»-aBaseDialog^AddAttribute(--id--4------------------ *--)------ >< 
+-,--attributeName-+ 


The AddAttribute method adds an attribute to the dialog object. The attribute is associated with the 
dialog control id. 


ooRexx OODialog Reference Version 4.0.0 113 


Chapter 5. BaseDialog Class 


Protected: 


This method is for internal use only. 


Arguments: 


The arguments are: 


id 
The ID of the dialog control. 

attributeName 
The name you want to give to the attribute. This name must comply with the conventions of 
Object Rexx for valid symbols. AddAttribute checks whether the argument is valid. In case of 
an invalid argument, an attribute with the name DATAid is created, where id is the value of the 
first argument. This method automatically removes blanks, ampersands (&), and colons (:). 

Example: 


The first and second lines generate the attributes Add and List all items. The third line generates 
the assembled attribute DATA34 because ListALLitems already exists. The fourth line creates 
attribute DATA35 because Update+Refresh is not a valid symbol name. 


self^AddAttribute(32, "&Add") 
self^AddAttribute(33, "List all items") 
self^AddAttribute(34, "ListALLitems:") 
self^AddAttribute(35, "Update+Refresh") 


5.6. Get and Set Methods 


Get methods are used to retrieve the data from all or individual controls of a dialog. Set methods are used 
to set the values of all or individual controls, without changing the associated Object Rexx attributes. 


5.6.1. GetData 


2»-aBaseDialog СеШана-----<-<--- сената 999 -- 9 >< 


The GetData method receives data from Ше Windows dialog and copies it to Ше associated object 
attributes. 


Example: 


The following example continues the SetData example: 


MyDialog^ConnectEntryLine(102, "ENTRYLINE 1") 
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MyDialog~ConnectCheckBox(201, ) 
MyDialog~ConnectListbox (203, "LISTBOX_DAYS") 


/* process the dialog */ 


MyDialog^GetData /* retrieve dialog item value */ 
say MyDialog^ ENTRYLINE 1 

say MyDialog~DATA201 

say MyDialog^LISTBOX DAYS 


5.6.2. SetData 


2»-aBaseDialog SetData---—-—------------------- oce ceci >< 


The SetData method transfers the values of the dialog object attributes, that are connected to dialog 
items, to the Windows dialog controls. See the section, Connect Attribute Methods for a discussion of 
connecting object attributes to the underlying dialog controls. 


Note that this method transfers the data for every connected attribute. This may not always be desirable. 
For instance the focused node of a tree-view control may be changed. For finely grained control of which 
values are transfered the programmer should use the setValue() or setAttribute() methods. Both of these 
methods transfer the value of a single object attribute that is specified by the programmer. 


Example: 


Dialog items with ID 102, 201 and 203 are connected to the attributes ENTRYLINE_1, DATA201, and 
LISTBOX_DAYS. Attribute DATA201 is generated by the ConnectCheckBox method. Then the attributes 
are initialized with some values. This does not change the dialog window, unless you run the 
SetData method. 


MyDialog^ConnectEntryLine(102, "ENTRYLINE 1") 
MyDialog^ConnectCheckBox(201,) 
MyDialog^ConnectListbox(203, "LISTBOX DAYS") 


MyDialog ENTRYLINE 1-"Memorial Day" 
MyDialog^DATA201-1 
MyDialog~LISTBOX_DAYS="Monday" 


MyDialog^SetData 
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5.6.3. ItemTitle 


»»-aBaseDialog^ItemTitle(--id--)------------------------------- >< 


The ItemTitle method returns the title of the given dialog item. 


Arguments: 


The only argument is: 


id 
The ID of the dialog item. 


5.6.4. SetStaticText 


>>-aBaseDialog~SetStaticText (--id--,--aString--)--------------- >< 


The SetStaticText method changes the text of a static text control. 


Arguments: 


The arguments are: 


id 
The ID of the static text control for which you want to change the text. 


aString 


The new text for the static text control. 


5.6.5. GetEntryLine 


»»-aBaseDialog^GetEntryLine(--id--)---------------------------- >< 


The GetEntryLine method returns the value of the given entry line. 


Arguments: 


The only argument is: 


id 
The ID of the entry line. 
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5.6.6. SetEntryLine 


»»-aBaseDialog^SetEntryLine(--id--,--aString--)---------------- >< 


The SetEntryLine method puts the value of а string into an entry line. 


Arguments: 


The arguments are: 
id 

The ID of the entry line. 
aString 


The value to be assigned to the entry line. 


Example: 


Assume that three methods are connected to push buttons. The SetToDefault method overrides the 
value in the Windows dialog entry line 234 with the value 256 but does not change its associated 
attribute. Using SetEntryLine has the same effect as a change to the entry line made by the user. The 
associated attribute in the Object Rexx object (DATA234) still has the original value. Thus it is 
possible to undo the changes or confirm them. 


::method SetToDefault 
Self^SetEntryLine(234, "256") 


::method AcceptValues 
self~GetAttrib(DATA234) 


::method UndoChanges 
self~SetAttrib (DATA234) 


5.6.7. GetListLine 


»»-aBaseDialog^GetListLine(--id--)----------------------------- >< 


The GetListLine method returns the value of the currently selected list item. If you need the index of the 
item, use the GetCurrentListIndex method. If no item is selected, a null string is returned. 


Arguments: 


The only argument is: 


id 
The ID of the list box. 
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5.6.8. SetListLine 


»»-aBaseDialog^SetListLine(--id--,--aString--)----------------- >< 


The SetListLine method assigns the value of a string to the list box. Thus the item with the value of 
aString becomes selected. The first item is selected if the string is not found in the list box. This method 
does not apply to a multiple selection list box (see SetMultiList). 


Arguments: 


The arguments are: 
id 

The ID of the list box. 
aString 


The value of the item to be selected. 


Example: 
The following example selects item "New York" in list box 232: 


MyBaseDialog^SetListLine(232, "New York") 


5.6.9. GetMultiList 


>>-aBaseDialog~GetMultiList (--id--)---------------------------- >< 


The GetMultiList method сап be applied to a multiple-selection list box. It returns a string containing the 
indexes of up to 1000 selected items. The numbers are separated by blanks. 


Arguments: 


The only argument is: 


id 


The ID of the multiple-selection list box. 


Example: 


The following example shows how to handle a multiple-selection list box. It parses the returned 
string as long as it contains an index. 


selLines = MyDialog~GetMultiList (555) 
do until selLines = "" 
parse var selLines aLine selLines 
say aLine 
end 
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5.6.10. SetMultiList 


»»-aBaseDialog^SetMultiList(--id--,--data--)------------------- >< 


The SetMultiList method selects опе or more lines in a multiple-selection list box. 


Arguments: 
The arguments are: 
id 
The ID of the multiple-selection list box. 
data 


The indexes (separated by blanks) of the lines to be selected. 


Example: 
The following example selects the lines 2, 5, and 6 of list box 345: 


MyDialog~SetMultiList (345, "2 5 6") 


5.6.11. GetComboLine 


»»-aBaseDialog^GetComboLine(--id--)---------------------------- >< 


The GetComboLine method returns the value of the currently selected list item of a combo box. If you 
need the index of the item, use the GetCurrentComboIndex method. If no item is selected, a null string is 
returned. 


Arguments: 


The only argument is: 


id 
The ID of the combo box. 


5.6.12. SetComboLine 


»»-aBaseDialog^SetComboLine(--id--,--aString--)---------------- >< 


The SetComboLine method assigns a string to the given combo box. Thus the item with the value of 
aString becomes selected. If aString is not found in the combo box, then the first item is selected. 
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Arguments: 


The arguments are: 


id 
The ID of the combo box. 


aString 


The value of the item to be selected. 


5.6.13. GetRadioButton 


»»-aBaseDialog^GetRadioButton(--id--)------------- 


------------- >< 


The GetRadioButton method returns 1 if the radio button is selected, 0 if it is not selected. 


Arguments: 


The only argument is: 


id 
The ID of the radio button. 


5.6.14. SetRadioButton 


»»-aBaseDialog^SetRadioButton(--id--,--data--)----------------- >< 


The SetRadioButton method marks the radio button if the given data value is 1, and removes the mark if 


the value is 0. 


Arguments: 


The arguments are: 


id 
The ID of the radio button. 


data 


1 to select the button or 0 to deselect it. 
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5.6.15. GetCheckBox 


»»-aBaseDialog^GetCheckBox(--id--)----------------------------- >< 


The GetCheckBox method returns the value of a check box: 1 if the check box is selected (has a check 
mark), 0 if it is not selected. 


Arguments: 


The only argument is: 


id 
The ID of the check box. 


5.6.16. SetCheckBox 


»»-aBaseDialog^SetCheckBox(--id--,--data--)-------------------- >< 


The SetCheckBox method puts a check mark in the check box if the given data value is | and removes 
the check mark if the value is 0. 


Arguments: 


The arguments are: 


id 
The ID of the check box. 


data 


The value 1 to check the box or 0 to remove the check mark. 


5.6.17. GetValue 


»»-aBaseDialog^GetValue(--id--)-------------------------------- >< 


The GetValue method gets the value of a dialog item, regardless of its type. The item must have been 
connected before. 
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Arguments: 
The only argument is: 
id 
The ID of the dialog item. 


5.6.18. SetValue 


»»-aBaseDialog^SetValue(--id--,--dataString--)----------------- >< 


The SetValue method sets the value of a dialog item. You do not have to know what kind of item it is. 
The dialog item must have been connected before. 


Arguments: 


The arguments are: 
id 

The ID of the dialog item. 
dataString 


The value that is assigned to the item. It must be a valid value. 


Example: 


The following example sets dialog item 123 to (string) value "1 2 3". This is meaningful if 123 is an 
entry field, or if it is a list box that contains the line "1 2 3". However, it is an error to apply this 
against a check box. 


MyDialog^SetValue(123, "1 2 3") 


Note: If it is a multiple-selection list box, the SetValue method does not look for an item with "1 2 3" 
as value but highlights the first, second, and third line. 


5.6.19. GetAttrib 


»»-aBaseDialog^GetAttrib(--attributeName--)-------------------- >< 


The GetAttrib method assigns the value of a dialog item to the associated Object Rexx attribute. It does 
not return a value. You do not have to know the ID or the type of the dialog item. 
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Arguments: 


The only argument is: 


attributeName 


The name of the attribute. 


Example: 
The following example shows how to get the data value of a dialog item without knowing its ID: 


MyDialog^GetAttrib("FirstName") 
if MyDialog”FirstName\="" then ... 


5.6.20. SetAttrib 


»»-aBaseDialog^SetAttrib(--attributeName--)-------------------- >< 


The SetAttrib method copies the value of an attribute to the associated dialog item. You do not have to 
know the ID or the type of the dialog item. 


Arguments: 


The only argument is: 


attributeName 


The name of the attribute. 


Example: 
The following example copies the value of the attribute DATA101 to the associated dialog item: 


MyBaseDialog^SetAttrib("DATA101") 


5.6.21. SetDataStem 


»»-aBaseDialog^SetDataStem(--dataStem.--)---------------------- >< 


The SetDataStem method sets all Windows dialog items to the values within the given stem; the suffixes 
of the stem variable are the dialog IDs. 


Protected: 


This method is protected. 
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Arguments: 


The only argument is: 


dataStem. 


A stem variable containing initialization data. Remember the trailing period. 


Example: 


The following example initializes the dialog items with ID 21, 22, and 23: 


dlgStem.21="Windows 95" 
dlgStem.22="0" 
dlgStem.23-"1 2 3" 
self^SetDataStem(dlgStem.) 


5.6.22. GetDataStem 


»»-aBaseDialog^GetDataStem(--dataStem.--)---------------------- >< 


The GetDataStem method gets the values of all dialog items and copies them to the given stem. 


Protected: 


This method is protected. 


Arguments: 


The only argument is: 


dataStem. 


The name of a stem variable to which the data is returned. Remember the trailing period. 


5.7. Standard Event Methods 


The following methods are abstract methods that are called each time a push button with ID 1, 2, or 9 is 
pressed. 


5.7.1. OK 


o> <аВазертаТов OK ss sss sass esses rare e >< 
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The OK method is called in response to a pressed OK button. It calls Validate to get its return code. The 
default return code is the self~finished attribute, which is usually 1, in which case the dialog is 
terminated. 


Protected: 


This method is protected. You might want to override it in your subclass. If you do, forward the OK 
message to the parent class after processing has finished. Set the self~finished attribute to 1 or 0 and 
return it. The dialog continues executing if you return the value 0. See also Validate. 


Example: 
The following example shows how to override the OK method: 
::method OK 
self~ok:super() 


self~finished = 1 
return self~finished 


5.7.2. Cancel 


»»-aBaseDialog Сапсе!-------------------------<----<-<-------<-<-< >< 


The Cancel method is called in response to a pressed Cancel button. The default return code is the 
self~finished attribute, which is usually 1, in which case the dialog is terminated. The InitCode attribute 
is set to 2 if the dialog is terminated. 


Protected: 


This method is protected. You might want to override it in your subclass. If you do, forward the 
Cancel message to the parent class after processing has finished. Set the self~finished attribute to 1 
or 0 and return it. The dialog continues executing if you return the value 0. 


5.7.3. Help 


2»-aBaseDralog Help-------—--—---------—------——ce Se ses ы ры ынша >< 


The Help method is called in response to a pressed Help button. 


Protected: 


This method is protected. You might want to override it in your subclass. 
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5.7.4. Validate 


»»-aBaseDialog Validate---------------------------------------- >< 


The Validate method is an abstract method that is called to determine whether the dialog сап be closed. 
This method is called by the OK method. The standard implementation is that Validate returns 1 and the 
dialog is closed. The dialog is not closed if Validate returns 0. 


Protected: 


The method is designed to be defined in a subclass. 


Example: 


In the following example Validate checks whether entry line 203 is empty. If it is empty, Validate 
returns 0, which indicates that the dialog cannot be closed. 


::class MyDialog subclass UserDialog 

: :method Validate 
if self^GetEntryLine(203) = "" then return 0 
else return 1 


5.7.5. Leaving 


»»-aBaseDialog^Leaving----------------------------------------- >< 


The Leaving method is called when the dialog was closed. 


5.7.6. Delnstall 


»»-aBaseDialog^DeInstall--------------------------------------- >< 


The DelInstall method removes the external functions from the Object Rexx API manager. It should be 
called at the end of each dialog. The installed functions are freed when all dialogs are finished. 


5.8. Combo Box Methods 


The following methods belong to combo boxes. 


5.8.1. AddComboEntry 


»»-aBaseDialog^AddComboEntry(--id--,--aString--)--------------- >< 
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The AddComboEntry method adds a string to the list of a combo box. The new item becomes the last 
one, if the list does not have the SORT flag set. In the case of a sorted list, the new item is inserted at the 
proper position. 


Arguments: 


The arguments are: 
id 

The ID of a combo box. 
aString 


The data to be inserted as a new line. 


Example: 
The following example adds the new line, Another item, to the list of combo box 103: 


MyDialog^AddComboEntry(103, "Another item") 


5.8.2. InsertComboEntry 
»»-aBaseDialog^InsertComboEntry (--id-- ,--+-------+-- ,--string--)->< 


+-іпаех-+ 


The InsertComboEntry method inserts а string into the list of a combo box. 


Arguments: 


The arguments are: 


id 
The ID of the combo box. 

index 
The index (line number) where you want to insert the new item. If this argument is omitted, the 
new item is inserted after the currently selected item. 

string 


The data string to be inserted. 


Example: 
This statement inserts The new third line after the second line into the list of combo box 103: 


MyDialog^InsertComboEntry(103, 2, "The new third line") 
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5.8.3. DeleteComboEntry 


>>-aBaseDialog~DeleteComboEntry (--id--,--index--)-------------- >< 


The DeleteComboEntry method deletes a string from the combo box. 


Arguments: 


The arguments are: 
id 
The ID of the combo box. 


index 


The line number of the item to be deleted. Use the FindComboEntry method (see 
pageFindComboEntry) to retrieve the index of an item. 


Example: 


The following example shows a method that deletes the item that is passed to the method in the 
form of a text string from combo box 203: 


::method DeleteFromCombo 
use arg delStr 
idx = self~FindComboEntry(203, delStr) 
self~DeleteComboEntry(203, idx) 


5.8.4. FindComboEntry 


>>-aBaseDialog~FindComboEntry (--id--,--aString--)-------------- >< 


The FindComboEntry method returns the index corresponding to a given text string in the combo box. 


Arguments: 


The arguments are: 


id 
The ID of the combo box 


aString 


The string of which you search the index in the combo box. 
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Example: 


See DeleteComboEntry for an example. 


5.8.5. GetComboEntry 


>>-aBaseDialog~GetComboEntry (--id--,--index--)----------------- >< 


The GetComboEntry method returns the string at index of the combo box. 


Arguments: 


The arguments are: 


id 
The ID of the combo box 


index 


The index of the list entry to be retrieved 


Example: 


if dlg~GetComboEntry (203,5) =" ЈОНМ" 
then ... 


5.8.6. GetComboltems 


>>-aBaseDialog~GetComboItems (--14--)--------------------------- >< 


The GetComboltems method returns the number of items in the combo box. 


Arguments: 


The only argument is: 


id 
The ID of the combo box 


5.8.7. GetCurrentCombolndex 


»»-aBaseDialog^GetCurrentComboIndex(--id--)-------------------- >< 
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The GetCurrentComboIndex method returns the index of the currently selected item within the list. See 
GetComboLine for information on how to retrieve the selected combo box item. 


Arguments: 


The only argument is: 


id 
The ID of the combo box. 


Example: 


The following example displays the line number of the currently selected combo box item within 
entry line 240: 


::class MyListDialog subclass UserDialog 


::method Init 
self^Init:super 
self^ConnectList(230, "ListSelected") 


::method ListSelected 
line = self^GetCurrentComboIndex(230) 
SetEntryLine(240, line) 


Method ListSelected is called each time the selected item within the combo box changes. 


5.8.8. SetCurrentCombolndex 


»»-aBaseDialog^SetCurrentComboIndex(--id--4---------- *--)------ >< 
+-,--index-+ 


The SetCurrentCombolndex method selects the item with the given index within the list. If called 
without an index, all items in the list are deselected. See SetComboLine for information on how to select 


a combo box item using a data value. 


Arguments: 


The arguments are: 


id 
The ID of the combo box. 
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index 


The index within the combo box. 


5.8.9. ChangeComboEntry 


>>-aBaseDialog~ ChangeComboEntry (--id-- ,--+-------+-- ,--aString-—)->< 
+-іпаех-+ 


The ChangeComboEntry method changes the value of a given entry in a combo box to a new string. 


Arguments: 


The arguments are: 


id 
The ID of the combo box 

index 
The index number of the item you want to replace. To retrieve the index, use the 
FindComboEntry ог GetCurrentComboIndex method (see page FindComboEntry or 
GetCurrentComboIndex). 

aString 
The new text. 

Example: 


In the following example, method ChangeButtonPressed changes the currently selected line of 
combo box 230 to the value in entry line 250: 


::method ChangeButtonPressed 
idx = self~GetCurrentComboEntry (230) 
str = self~GetEntryLine (250) 
self~ChangeComboEntry(230, idx, str) 


5.8.10. ComboAddDirectory 


»»-aBaseDialog^ComboAddDirectory(--id--,--drvpath--,------------- ? 
4--------------- + 
ү | 
>--"----+-ВЕАРИВ1ТЕ-+-+--"--)----------------------------------- >< 


+-READONLY--+ 
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+-HIDDEN----+ 
+-SYSTEM----+ 
+-DIRECTORY-+ 
+-ARCHIVE---+ 


The ComboAddDirectory method adds all or selected file names in the given directory to the combo box. 


Arguments: 


The arguments are: 


id 
The ID of the combo box. 


drvpath 


The drive, path, and name pattern. 


fileAttributes 


Specify the file attributes that the files must have in order to be added: 


READWRITE 


Normal read/write files (same as none). 


READONLY 


Files that have the read-only bit. 


HIDDEN 
Files that have the hidden bit. 


SYSTEM 


Files that have the system bit. 


DIRECTORY 


Files that have the directory bit. 


ARCHIVE 


Files that have the archive bit. 


Example: 


The following example fills the combo box list with the names of all read/write files with extension 
-REX in the given directory: 


MyDialog~ComboAddDirectory(203, drive":\"path"\*.rex", "READWRITE") 
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5.8.11. ComboDrop 


»»-aBaseDialog^ComboDrop(--id--)------------------------------- >< 


The ComboDrop method deletes all items from the list of the given combo box. 


Arguments: 


The only argument is: 


id 
The ID of the combo box. 


5.9. List Box Methods 


The following methods deal with list boxes. 


5.9.1. GetListWidth 


»»-aBaseDialog^GetListWidth(--id--)---------------------------- >< 


The GetListWidth method returns the scrollable width of а list box, in dialog units. 


Arguments: 


The only argument is: 


id 


The ID of the list box of which you want to know the scrollable width. 


Return value: 


The width of the scrollable area of the list box, in dialog units. 


5.9.2. SetListWidth 


»»-aBaseDialog^SetListWidth(--id--,--scrollwidth--)------------ >< 


The SetListWidth method sets the scrollable width of a list box, in dialog units. If the scrollable width is 
greater than the width of the list box and the "HSCROLL" (WS_HSCROLL in the resource script) style 
is defined for the list box (see addListBox), a horizontal scroll bar is displayed. 
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Arguments: 


The arguments are: 


id 
The ID of the list box for which you want to set the scrollable width. 


scrollwidth 


The width of the scrollable area of the list box, in dialog units. 


Return value: 


This method does not return a value. 


5.9.3. SetListColumnWidth 


»»-aBaseDialog^SetListColumnWidth(--id--,--columnwidth--)------ >< 


The SetListColumn Width method sets the width of all columns in a list box, in dialog units. 


Arguments: 


The arguments are: 


id 
The ID of the list box for which you want to set the column width. 


columnwidth 


The width of the columns in the list box, in dialog units. 


Return value: 


This method does not return a value. 


5.9.4. AddListEntry 


>>-aBaseDialog~ AddListEntry (--id--,--aString--)---------------- >< 


The AddListEntry method adds a string to the given list box. See also AddComboEntry. The line is 
added at the end (by default), or in sorted order if the list box was defined with the sorted flag. 
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Arguments: 


The arguments are: 
id 
The ID of a list box. 


aString 


The data to be inserted as a new line. 


5.9.5. InsertListEntry 


»»-aBaseDialog^InsertListEntry (--id-- ,--+-------+-- ,--aString-—)->< 
+-іпаех-+ 


The InsertListEntry method inserts а string into the given list box. See also InsertComboEntry. 


Arguments: 


The arguments are: 
id 
The ID of the list box. 


index 


The index (line number starting with 1) of the item after which the new item is inserted. If this 
argument is omitted, the new item is inserted after the currently selected item. 


aString 


The text string to be inserted. 


5.9.6. DeleteListEntry 


»»-aBaseDialog^DeleteListEntry(--id--,--index--)--------------- >< 


The DeleteListEntry method deletes an item from a list box. See also DeleteComboEntry. 


Arguments: 


The arguments are: 


id 
The ID of the list box. 


ooRexx OODialog Reference Version 4.0.0 135 


Chapter 5. BaseDialog Class 


index 


The line number of the item to be deleted. Use FindListEntry to retrieve the index of an item. If 
this argument is omitted, the currently selected item is deleted. 


5.9.7. FindListEntry 


»»-aBaseDialog^FindListEntry(--id--,--aString--)--------------- >< 


The FindListEntry method returns the index of the given string within the given list box. The first item 
has index 1, the second has index 2, and so forth. If the list box does not contain the string, 0 is returned. 


Arguments: 
The arguments are: 
id 
The ID of the list box. 
aString 


The item text you are looking for. 


Example: 


The following example shows a method that adds the contents of an entry line (214) to the list box 
(215) if no item with the same value is already contained in it: 


::method PutEntryInList 
str = self~GetEntryLine (214) 
if self^FindListEntry(215, str) = 0 then 
self~AddListEntry(215, str) 


5.9.8. GetListEntry 


»»-aBaseDialog^GetListEntry(--id--,--index--)------------------ >< 


The GetListEntry method returns the string at index of the list. 
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Arguments: 


The arguments are: 


id 
The ID of the list box. 


index 


The index of the list entry to be retrieved. 


Example: 


if dlg^GetListEntry (203,5) =" ЈОНМ" 
then ... 


5.9.9. GetListltems 


»»-aBaseDialog^GetListItems(--id--)---------------------------- >< 


The GetListItems method returns the number of items in the list box. 


Arguments: 


The only argument is: 


id 
The ID of the list box. 


5.9.10. GetListltemHeight 
>>-aBaseDialog~GetListItemHeight (--id--)----------------------- >< 
The GetListItemHeight method returns the height of the items in a list box, in dialog units. 


Arguments: 


The only argument is: 


id 


The ID of the list box of which you want to know the item height. 
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Return value: 


The height of the list box items, in dialog units. 


5.9.11. SetListltemHeight 


»»-aBaseDialog^SetListltemHeight (--id--,--itemheight--)-------- >< 


The SetListItemHeight method sets the height for all items in a list box, in dialog units. It determines the 
space between the individual list box items. 


Arguments: 


The arguments are: 


id 
The ID of the list box for which you want to set the item height. 


itemheight 


The height of the items in the list box, in dialog units. 


Return value: 


A number smaller than 0 if the height that you specify is not valid. 


5.9.12. GetCurrentListindex 


»»-aBaseDialog^GetCurrentListIndex(--id--)--------------------- >< 


The GetCurrentListIndex method returns the index of the currently selected list box item, or 0 if no item 
is selected. See GetListLine for information on how to retrieve the selected list box item. 


Arguments: 


The only argument is: 


id 
The ID of the list box. 


5.9.13. SetCurrentListlndex 


»»-aBaseDialog^SetCurrentListIndex(--id--4---------- 4--)------- >< 
+-,--index-+ 
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The SetCurrentListIndex selects the item with the given index in the list. If called without an index, all 
items in the list are deselected. See SetListLine for information on how to select a list box item using a 
data value. 


Arguments: 
The arguments are: 
id 
The ID of the list box. 


index 


The index within the list box. 


5.9.14. ChangeListEntry 


>>-aBaseDialog~ChangeListEntry (--id--,--4-------4--,--aString--)-»« 
+-іпаех-+ 


The ChangeListEntry method changes the contents of a line in а list box. 


Arguments: 
The arguments are: 
id 
The ID of the list box. 


index 


The index of the item that you want to replace. If this argument is omitted, the currently 
selected item is changed. 


aString 


The new text of the item. 


5.9.15. SetListTabulators 


+-,---+ 


»»-aBaseDialog^SetListTabulators(--id--,----tab-4--)----------- >< 


The SetListTabulators method sets the tabulators for a list box. Thus you can use items containing tab 
characters ("09"x), which is useful for formatting the list in more than one column. 
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Arguments: 


The arguments are: 


id 
The ID of the list box. 


tab 


The positions of the tabs relative to the left edge of the list box. 


Example: 


The following example creates a four-column list and adds a tab-formatted row to the list. The 
tabulator positions are 10, 20, and 30. 


MyDialog^SetListTabulators(102, 10, 20, 30) 
MyDialog^AddListEntry(102, vari  "O9"x 
var2 "09"x 


var3 "09"х var4) 


5.9.16. ListAddDirectory 


>>-aBaseDialog~ListAddDirectory (--id--,--drvPath--,--"----*-READWRITE-4-4--"--)-5« 
+-READONLY--+ 
+-HIDDEN----+ 
+-SYSTEM----+ 
+-DIRECTORY-+ 
+-ARCHIVE---+ 


The ListAddDirectory method adds all or selected file names of a given directory to the list box. See 
ComboAddDirectory for more information. 


5.9.17. ListDrop 


»»-aBaseDialog^ListDrop(--id--)------------------------------- >< 


The ListDrop method removes all items from the list box. 


Arguments: 


The only argument is: 


id 
The ID of the list box. 
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5.10. Scroll Bar Methods 


The following methods are used to set or get the behavior of a scroll bar. You can connect scroll bars 
with numerical entry fields to edit the value with the mouse. 


5.10.1. GetSBRange 


»»-aBaseDialog^GetSBRange(--id--)----------------------------- >< 


The GetSBRange method returns the range of a scroll bar control. It returns the two values (minimum 
and maximum) in one string, separated by a blank. 


Protected: 


This method is protected. 


Arguments: 


The only argument is: 


id 
The ID of the scroll bar. 


Example: 


The following example demonstrates how to get the minimum and the maximum values of the 
scroll bar: 


::method DumpSBRange 

SBrange = self~GetSBRange (234) 
parse var SBrange SBmin SBmax 
say SBmin " - " SBmax 


5.10.2. SetSBRange 


+-1------ + 
>>-aBaseDialog~ SetSBRange (--id-- ,--min-- , --max-- ,--+--------+--) ->< 
+-redraw-+ 


The SetSBRange method sets the range of a scroll bar control. It sets the minimum and maximum values. 


Protected: 


This method is not intended to be used outside of the BaseDialog class. 
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Arguments: 
The arguments are: 
id 
The ID of a scroll bar control. 
min 
The minimum value. 


max 


The maximum value. 


redraw 


A flag indicating whether (1) or not (0) the scroll bar should be redrawn. The default is 1. 


Example: 
The following example allows the scroll bar to take values between 1 and 10: 


MyDialog^SetSBRange(234, 1, 10, 1) 


5.10.3. GetSBPos 


»»-aBaseDialog^GetSBPos(--id--)------------------------------- >< 


The GetSBPos method returns the current value of a scroll bar control. 


Arguments: 


The only argument is: 


id 
The ID of the scroll bar. 


5.10.4. SetSBPos 


+-1------ + 
»»-aBaseDialog^SetSBPos(--id--,--pos--,--*-------- +--)-------- >< 
+-redraw-+ 


The SetSBPos method sets the current value of a scroll bar control. 
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Protected: 


This method is protected. 


Arguments: 


The arguments are: 
id 
The ID of the scroll bar. 


pos 


The value to which you want to set the scroll bar. It must be within the defined range. 


redraw 


A flag indicating whether (1) or not (0) the scroll bar should be redrawn. The default is 1. 


5.10.5. CombineELwithSB 


»»-aBaseDialog^CombineELwithSB(--elid--,--sbid--4------------------------- +--) ->< 
+-,--+------+--+--------+-+ 


+-step-+ +-,--pos-+ 


The CombineELwithSB method connects an entry line with a scroll bar such that each time the slider of 
the scroll bar is moved, the value of the entry field is changed. This method must be used in a method 
registered with ConnectScrollBar. 


Arguments: 


The arguments are: 


elid 
The ID of the entry line. 
sbid 
The ID of the scroll bar. 
step 
The size of one step. If, for example, step is 3 and the current position is 4, the next position is 
7. 
pos 


If the step value is zero, this sets the position of the scroll bar and entry line. Use it in the 
method registered for drag. 
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Example: 


The following example continues the example of ConnectScrollBar. In the registered methods an 
entry line (251) is combined with the scroll bar (255). 


::method Increase 

self~CombineELwithSB (251,255 ,+20) 

::method Decrease 

self ~CombineELwithSB (251 ,255,-20) 

::method Drag 

use arg wparam, lparam /* wparam=position */ 
self~CombineELwithSB (251,255 ,0,wparam) 


5.10.6. DetermineSBPosition 


»»-aBaseDialog^DetermineSBPosition(--id--,--posdata--4---------------------------- +--) ->< 
+-,--+-------- +--+--------- +-+ 


+-single-+ +-,--раре-+ 


The DetermineSBPosition method calculates and sets the new scroll bar position based on the position 
data retrieved from the scroll bar and the step information. 


Protected: 


This method is protected. 


Arguments: 


The arguments are: 


id 
The ID of the scroll bar. 


posdata 


The position information sent with the connected scroll bar event. 


single 


This number is added (or subtracted if negative) to the current position for a single step. If 
omitted, the single step size is 1. 


page 
This number is added (or subtracted if negative) to the current position for a page step. If 
omitted, the page step size is 10. 


Return value: 


The new scroll bar position. 
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Example: 


The following example demonstrates how to update the scroll bar position. Each time the 
ScrollBarEventHandler is called by an event for scroll bar SB_SIZE, the position of the scroll bar is 
calculated and updated. posdata is sent along with the scroll bar event. 


/* Method ScrollBarEventHandler is connected to item SB SIZE */ 
::method ScrollBarEventHandler 

use arg posdata, sbwnd 

pos = self^DetermineSBPosition("SB, SIZE",posdata,1,25) 

return pos 


5.11. Methods to Query Operating System Values 


The methods in this section return information known to, or used by, the operating system when it works 
with dialogs or dialog controls. This includes things like window handles, window sizes, and window 
positions. It also includes things like the width of a scroll bar or the number of monitors attached to the 
system. 


5.11.1. GetSelf 


22»-aBaseDialog Себе! +#-------------------------- >< 


The GetSelf method returns Ше handle of the Windows Dialog associated with Ше ooDialog dialog 
instance. A handle is a unique reference to a particular Windows object. Handles are used within some of 
the methods to work on a specific Windows object. 


Note: Prior to ooRexx 3.2.0, the GetSe1f method was not documented. The Get method was 
documented as if it were the GetSe1f method. The Get method returns the handle to the most 
recently created dialog. In an application with more than one dialog this may not be the same as the 
Windows dialog associated with the instance object the programmer is working with. 


Example: 


Below is an example demonstrating these Windows handles and how they are related. Assume 
showHandles is a method of a subclass of BaseDialog and that staticDlg is a saved reference to 
another ooDialog object and that the static dialog was just created. The showHandles method is 
connected to a push button and then displays the handles when the user clicks that button. 


::method showHandles 
expose staticDlg 


hwndTop = self^get 


hwndMyDialogHandle - self^dlgHandle 
hwndMySelf - self^getSelf 
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hwndStatic = staticDlg^dlgHandle 


say "Top dialog: " hwndTop 

say "Self (dlgHandle):" hwndMyDialogHandle 

say "Self (getSelf): " hwndMySelf 

say "Static dialog: " hwndStatic 
Output: 


The above might write to the console something like the following: 


Top dialog: 787096 
Self (dlgHandle): 4522228 
Self (getSelf): 4522228 
Static dialog: 787096 


5.11.2. Get 


>>-аВазертатов`беъ--=--=--=====-==--===-=--==-=5------5=-5==5--= >< 


The Get method returns the handle of the Windows Dialog associated with the top ooDialog dialog. А 
handle is a unique reference to a particular Windows object. Handles are used within some of the 
methods to work on a specific Windows object. 


Note: If more than one ooDialog exists, the top dialog and the dialog whose method is executing may 
not be the same. When more than one dialog exists, the top dialog is the one that was created last. 


Example: 


Below is an example demonstrating that the top dialog and the executing dialog may not be the 
same. Assume display is a method of a subclass of BaseDialog and that staticDlg is a saved 
reference to another ooDialog object. 
::method display 

expose staticDlg 


hwndTop = self^get 

hwndSelf = self^dlgHandle 
hwndStatic = staticDlg~dlgHandle 
say "Top dialog: " hwndTop 

say "Self: " hwndSelf 
say "Static dialog:" hwndStatic 


Output: 
The above might write to the console something like the following: 
Top dialog: 787096 
Self: 4522228 


Static dialog: 787096 
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5.11.3. Getltem 


»»-aBaseDialog^GetItem(--id--4--------- a ше ез-шн ышы >< 
*-,--hDlg-* 


The GetItem method returns the handle of a particular dialog item. 


Arguments: 
The arguments are: 
id 
The ID of the dialog element. 
hDlg 


The handle of the dialog. If it is omitted, the main dialog handle is used. 


Example: 
The following example returns the handle of a push button: 


hndPushButton = MyDialog^GetlItem(101) 


5.11.4. GetControllD 


»»-aBaseDialog^GetControlID(--hWnd--)------------------------- >< 


Given a valid window handle to a dialog control, the GetControlID method returns the resource ID of the 
control. 


Arguments: 


The only argument is: 


hWnd 


The window handle of the dialog control. 


Return value: 


Negative values indicate an error. 


-1 


The hWnd argument is not a valid window handle. 
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less than -1 


The value is the negated Operating System Error code. The absolute value of the return can be 
used to look up the error reason in the Windows documentation. 


other 


The resource ID of the dialog control. 


Example: 


The following is a complete working example. It allows the user to check a check box with the F2 
key and uncheck it with the F3 key. The F2 and F3 key press events are connected to the check and 
uncheck methods. When the user presses the F2 key, the program determines which control has the 
focus, uses the returned window handle to get the control ID, and then uses the ID to check the 
check box. And the same approach if the F3 key is pressed. 


Note that in this dialog, there are only four controls that can have the focus. If the OK button has the 
focus, then nothing is done. In a more complex application, the programmer would probably check 
that the resource ID matches one of the check boxes instead. 


/* Simple Grocery List */ 


dlg = .SimpleDialog^new 
dlg~constDir[IDC_GB_LIST] 101 
dlg~constDir [IDC_CB_MILK] 102 
dlg^constDir[IDC. CB BREAD] = 103 
dlg^constDir[IDC. СВ FRUIT] = 104 
dlg^constDir[IDC CB CEREAL] = 105 


if dlg~initCode = 0 then до 
dlg^create(30, 30, 150, 150, "The Simple Grocery List", "VISIBLE") 
dlg^Execute("SHOWTOP") 
dlg^Deinstall 

end 


-- End of entry point. 
::requires "oodWin32.cls" 


::class SimpleDialog subclass UserDialog inherit AdvancedControls MessageExtensions 
::method check 

hWnd - self^getFocus 

id = self^getControlID(hWnd) 

if id == self^constDir[IDOK] then return 

self^getCheckControl(id)^check 


::method unCheck 


id = self^getControlID(self^getFocus) 
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if id == self~constDir[IDOK] then return 
self ~getCheckControl (id) ~uncheck 


::method defineDialog 


self^addGroupBox(10, 20, 130, 90, "Check Needed Groceries", "", IDC GB LIST); 
self^addCheckBox(IDC CB MILK, , 30, 35, , , "Milk", "GROUP"); 
self^addCheckBox(IDC CB BREAD, , 30, 55, , , "Bread", "NOTAB"); 
self^addCheckBox(IDC CB FRUIT, , 30, 75, , , "Fruit", "NOTAB"); 
self^addCheckBox(IDC CB CEREAL, , 30, 95, , , "Cereal", "NOTAB"); 
self^addButton(IDOK, 105, 120, 35, 15, "OK", , "GROUP") 





::method initDialog 


-- We know that the key code for F2 is 113 so we don't need to use the 

-- VirtualKeyCodes class. We use the "none? filter so that only a F2 or ЕЗ 
-- key press is captured. (Not Alt-F2, or Shift-F2, etc..) 
self^connectKeyPress(check, 113, "NONE") 

self^connectKeyPress(unCheck, 114, "NONE") 


5.11.5. getPos 


PP =SBet ROS = Sr st sees Se Ser Sse SSS Sr esse ---#---<-+<<<- >< 


The getPos method returns the coordinates of the upper left corner a window, either a dialog or a dialog 
control, in dialog units. 


Return value: 


The horizontal and vertical position, separated by a blank. 


Example dialog control: 


The following example repositions the tree view control FILES to the upper left corner of the 
window and displays the new position: 


obj = MyDialog~GetTreeControl ("FILES") 

if obj = .Nil then return 

obj ~Move(1,1) 

parse value obj getPos with x y 

say "New horizontal position of window is" x "and new vertical position is" y 


Example dialog: 
The following example moves the window towards the top left of the screen. 


parse value self^getPos with px py 
self^Move(px - 10, py - 10) 


ooRexx OODialog Reference Version 4.0.0 149 


Chapter 5. BaseDialog Class 


5.11.6. GetButtonRect 


»»-aBaseDialog^GetButtonRect (--id--)-------------------------- >< 


The GetButtonRect method returns the size and position of the given button. The four values (left, top, 
right, bottom) are returned in one string separated by blanks. 


Arguments: 


The only argument is: 


id 
The ID of the button 


5.11.7. GetWindowRect 


»»-aBaseDialog^GetWindowRect (--hwnd--)------------------------ >< 


The GetWindowRect method returns the size and position of the given window. The four values (left, 
top, right, bottom) are returned in one string separated by blanks. 


Arguments: 


The only argument is: 


hwnd 


The handle of the window. There are a number of ways to get the window handle of objects 
used in ooDialog. For instance, use the GetSelf method to retrieve the window handle of the 
dialog instance. Use the Get method to retrieve the window handle of the most recently created 
dialog. To get the window handle to a dialog control, the GetItem method can be used. 


5.11.8. getSystemMetrics (deprecated) 


Note: This method is deprecated. It is replaced by the functionally equivalent getSystemMetrics() 
method of the .DIgUtil class. Do not use this method in new code. Try to migrate existing code to to 
the .DlgUtil~getSystemMetrics() method. This method may not exist in future versions of ooDialog. 
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5.12. Appearance and Behavior Methods 


The methods listed in this section are related to the appearance or the behavior of the dialog or its 
controls. The section contains methods related to size, position, visibility, and title. 


Some of the methods come in two flavors, normal (for example, Show Window and fast (for example, 
Show WindowFast). The fast extension indicates that the method does not redraw the control or window 
immediately. After modifying several items, invoke the Update method (see page Update) to redraw the 
dialog. 


5.12.1. getTextSizeDlg 


>>--getTextSizeDlg (--text--+------------- a a +--)---->< 
+-,-fontname--+ +-,-fontSize--+ +-,-hwnd--+ 


Calculates the size, (width and height,) needed to display the given text in the specified font. The size is 
expressed in dialog units. To calculate the size in pixels use the getTextSizeScreen() method. 


In general, dialog units are only of value in laying out the dialog controls before the underlying dialog is 
created. Once the underlying dialog is created, it makes more sense to work with pixels. Historically, the 
ooDialog documentation did not make that distinction clear. In addition, dialog units are tied directly to 
the font used by a dialog. Therefore, it does not make much sense for this method to be an instance 
method of a dialog control. 


The normal use of this method would be to invoke it on a dialog object to help layout the dialog’s 
controls prior to the creation of the underlying dialog. In this use case, the hwnd argument is 
meaningless. There is no handle to either the dialog window or any of its controls, prior to the underlying 
dialog creation. There is little point in using a window handle from some other dialog. However, to 
maintain compatibility with previous versions of ooDialog, the hwnd argument remains, and the method 
is still an instance method of a dialog control. 


This method replaces the deprecated getTextSize() method. The compatibility restraint is a result of this. 
The compatibility restraint makes it harder than necessary to document exactly how this method works, 
because the behavior is different in places if the method is inovked on a dialog object or on a dialog 
control object. 


The ooDialog programmer is strongly encouraged to only inovke this method through a dialog object. 
Future versions of ooDialog may remove this method from the instance methods of the DialogControl 
class. 


Arguments: 


The arguments are: 


text 


The string whose size is desired. If none of the optional arguments are specified then the dialog 
font is used to calculate the size. 


However, there are some exceptions to this if the method is invoked after the underlying dialog 
is created. 
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1. If this method is invoked through a dialog control object, then the size is calculated using 
the dialog control font. This usage is deprecated and the ooDialog programmer is strongly 
encouraged to not use this method in this manner. 


2. If the fourth, optional, hwnd argument is used, then the font of that window is used to 
calculate the size. Again, the ooDialog programmer is strongly encouraged to not use this 
method in this manner. 


fontName 
Optional. The name of the font to use to calculate the size needed for the string. Use This 
argument when the string will be displayed in a font different than the dialog font. 

fontSize 
Optional. The size of the font named by the fontName argument. If this argument is omitted 
then the defualt font size is used. (Currently the default size is 8.) 

hwnd 


Optional. A valid window handle. The font of this window is used to calculate the text size. 
This argument is always ignored when the fontName argument is specified. As per the notes 
above the ooDialog programmer is encouraged not to use this argument. 


Return value: 


The size needed for the string is returned in a Size object. The size is specified in dialog units. 


Example: 


This example calculates the size needed to display a message. It then uses that size to create an 
object that holds the co-ordinates needed to place the text in a dialog. This is used in defineDialog() 
to add the message text to the dialog. 


size = се| Е getTextSizeDlg (message) 


messageRect = .directory^new 
messageRect^x - 10 
messageRect^y - 10 


messageRect^cx = size^width 
messageRect^cy = size^ height 


::method defineDialog 
expose message messageRect okRect 


r - messageRect 
self^addText(r^x, r^y, r^cx, r^cy, message) 
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5.12.2. BackgroundColor 


»»-aBaseDialog^BackgroundColor(--color--)--------------------- >< 


The BackgroundColor method sets the background color of a dialog. 


Arguments: 


The only argument is: 


color 


A color-palette index specifying the background color. For information on the color numbers, 
refer to Definition of Terms. 


Return value: 


This method does not return a value. 


5.12.3. Show 


*-NORMAL----* 
»»-aBaseDialog^Show(--"--4---------- *--"--)-------------------- >< 

+-DEFAULT--+ 

+-SHOWTOP--+ 


+-HIDE----- + 
+-MIN------ + 
*-MAX------ * 


+-INACTIVE-+ 


The Show method shows the dialog. It is called by Execute or ExecuteAsync methods to initially display 
the dialog. Once the dialog has been initially shown, the programmer can use the Show to change the 
appearance of the dialog. For instance the dialog can be hidden, maximized, minimized, etc.. 


Argument: 


The argument can be one of the following keywords, case is not significant: 


NORMAL 


Makes the dialog visible with its default window size. This is the default keyword if the 
argument is omitted. 


DEFAULT 


DEFAULT is an alias for NORMAL. The two keywords are functionally identical. 


SHOWTOP 


Shows and makes the dialog the topmost dialog. 
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HIDE 
Makes the dialog invisible. 


MIN 


Minimizes the dialog. 


MAX 


Maximizes the dialog. 


INACTIVE 


Shows the dialog without changing the active window. When the Normal keyword is used, the 
dialog is shown and becomes the active window. Using the INACTIVE keyword allows the 
dialog to be shown and let another window remain active. 


Example: 
The following statement hides the dialog: 


MyDialog^Show("HIDE") 


5.12.4. ToTheTop 


»»-aBaseDialog ToTheTop---------------------------------------- >< 


The ToTheTop method makes the dialog the topmost dialog. 


Example: 


The following example uses the ToTheTop method to make the user aware of an alarm event: 


aDialog = .MyDialog^new 
msg = .Message^new(aDialog, "Remind") 
a = .Alarm^new("17:30:00", msg) 


::class MyDialog subclass UserDialog 


::method Remind 
self~SetStaticText(102, "Don't forget to go home!") 
self~ToTheTop 


Note: The Message and Alarm classes are built-in classes of Object Rexx. See the Open Object 
Rexx: Reference for further information. 
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5.12.5. EnsureVisible 


»»-aBaseDialog^ EnsureVisible----------------------------------- >< 


The EnsureVisible method causes the dialog to reposition itself so that the entire dialog is on the visible 
screen. If the entire dialog is already on the visible screen then no action is taken. 


This is useful in a number of situations. It allows the programmer to move or resize the dialog and not 
have to worry that the dialog is off the screen. After finishing the move or resizing, the programmer can 
invoke the EnsureVisible method and know that the dialog is entirely on the screen. 


Arguments: 


The method takes no arguments. 


Return value: 


This method always returns 0. 


Example: 


The following example reads in the previous size and position of the dialog and then opens the 
dialog in the position that the user had closed it. If the INI file is corrupted, or had been accidently 
edited, or a number of other things, it is possible that sizing and positioning the dialog using the 
values from the INI file will place the dialog of the screen. Invoking EnsureVisible will cause the 
dialog to reposition itself so that it is completely on the screen, but only if needed. If the dialog is 
already completely on the screen, then no action is taken. 


if \.useDefault then 
do 
-- Read oorexxtry.ini position & size the dialog based on its values 
handle = self^getSelf() 


ki = SyslIni(?oorexxtry.ini?,"oorexxtry! ,"k1?) 
k2 = SysIni(’ oorexxtry.ini’,’oorexxtry’,’k2’) 
КЗ = SysIni(’ oorexxtry.ini’,’oorexxtry’,’k3’) 
k4 = SysIni(’ oorexxtry.ini’,’oorexxtry’,’k4’) 
if ki = ’ERROR:’ | k2 = ’ERROR:’ | КЗ = ’ERROR:’ | k4 = ’ERROR:’ then 
nop -- First execution will not find the ini file 
else 
do 
self~setWindowRect (handle,k1,k2,k3-k1i,k4-k2) 
self^ensureVisible 
end 
end 


5.12.6. Minimize 


>> -аВазертаТов Ми 2в----------- + n те ---- 3594 -5---- >< 
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The Minimize method minimizes the dialog to the taskbar. This is the identical to the user clicking the 
minimize button on the dialog window. This method will minimize the dialog even if it does not have the 
MINIMIZEBOX style when it is created. 


This is a convenience method. It is functionally equivalent to using the Show method with the MIN 
keyword. 


Arguments: 


The method takes no arguments. 


Return value: 


0 
Minimizing was successful. 
1 
Minimizing failed. 
Example: 


This example creates a secondary dialog to display the contents of a file. The secondary dialog is 
show full screen (maximized.) At the same time the parent dialog is minimized to the taskbar. The 
complete program listing is available (see the File Viewer example.) 


::method onView 
expose viewDlg editCntrl 


fileName - editCntrl^getText 

viewDlg - .Viewer^new( , "fileView.h", self, fileName) 

if viewDlg^initCode = 0 then do 
self^disableItem(IDC. PB VIEW) 


viewDlg^create(30, 30, 170, 180, "Viewer", "MAXIMIZEBOX MINIMIZEBOX") 
viewDlg^popUpAsChild(self, "HIDE", , IDI_DLG_APPICON) 


-- The underlying Windows dialog has to be created before it can be maximized. 
j = SysSleep(.1) 


viewDlg” maximize 
self^minimize 
end 


5.12.7. Maximize 


»»-aBaseDialog Maximize------------------------------c--------4 >< 
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The Maximize method maximizes the dialog on the screen. This is the identical to the user clicking the 
maximize button on the dialog window. This method will maximize the dialog even if it does not have 
the MAXIMIZEBOX style when it is created. 


This is a convenience method. It is functionally equivalent to using the Show method with the МАХ 
keyword. 


Arguments: 


The method takes no arguments. 


Return value: 


0 
Maximizing was successful. 
1 
Maximizing failed. 
Example: 


The following code snippet minimizes the dialog to the taskbar. It is used in the File Viewer 
example. The complete program listing is available (see the File Viewer example.) 


::method onView 
expose viewDlg editCntrl 


if viewDlg~initCode = 0 then до 


viewDlg” maximize 
self^minimize 
end 


5.12.8. Restore 


22»-aBaseDialog Невъоге---------------------<--- >< 


The Restore method restores a minimized or maximized dialog to its original position. This is the 
identical to the user taking action to restore the dialog window. The programmer can use this method to 
restore a dialog window that he previously minimized or maximized. 


This is a convenience method. It is functionally equivalent to using the Show method with the RESTORE 
keyword. 
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Arguments: 


The method takes no arguments. 


Return value: 


0 
Restoring was successful. 
1 
Restoring failed. 
Example: 


The following example checks if the parent dialog is minimized and, if it is, the Restore method is 
used to show the dialog in the size and position it was prior to being minimized. The complete 
program listing for this code snippet is available (see the File Viewer example.) 


::method cancel 
expose parent 


parent^enableItem(IDC. PB VIEW) 
if parent^isMinimized then parent^restore 


return self^cancel:super 


5.12.9. IsMinimized 


>>-aBaseDialog™ IsMinimized-------------------------c--cco---c-o >< 


The IsMinimized method is used to check if a dialog is currently minimized. 


Arguments: 


The method takes no arguments. 


Return value: 


„пие 


The dialog is minimized. 


false 


The dialog is not minimized. 
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Example: 


The following example checks if the parent dialog is minimized and, if it is, the Restore method is 
used to show the dialog in the size and position it was prior to being minimized. The complete 
program listing that this code snippet comes from is available (see the File Viewer example.) 


::method cancel 
expose parent 
parent^enableItem(IDC. PB VIEW) 
if parent^isMinimized then parent^restore 
return self^cancel:super 


5.12.10. IsMaximized 


»»-aBaseDialog" IsMaximized------------------------------------4 >< 


The IsMaximized method is used to check if a dialog is currently maximized. 
Arguments: 
The method takes no arguments. 


Return value: 


.true 


The dialog is maximized. 


false 


The dialog is not maximized. 


Example: 


The following code snippet would check if the dialog is maximized and, if it is, restore it to the 
position and size it was prior to being maximized. 


if self~isMaximized then self~restore 


5.12.11. Focusltem 


»»-aBaseDialog^FocusItem(--id--)------------------------------ >< 


The FocusItem method sets the input focus to a particular dialog item. 
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Arguments: 


The only argument is: 


id 


The ID of the dialog item to set the focus to 


Return value: 


This method always returns 1. 


5.12.12. TabToNext 


»»-aBaseDialog TabToNext-------------------------------------- >< 


The TabToNext method sets the input focus to the next dialog control with a tab stop. This performs the 
same action as if the user pressed the tab key in the dialog. Like many of the other methods, TabToNext 
is a method of both a BaseDialog and a DialogControl. 


Return value: 


-1 

The method failed. 
0 

The focus was changed, but the control with the previous focus could not be determined. 
Other 


The handle to the control with the previous focus. 


5.12.13. TabToPrevious 


»»-aBaseDialog TabToPrevious---------------------------------- >< 


This method is the reverse of TabToNext and sets the input focus to the previous dialog control with a tab 
stop. This performs the same action as if the user pressed the shift-tab key in the dialog. TabToPrevious 
is a method of both a BaseDialog and a DialogControl. 
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Return value: 


-1 

The method failed. 
0 

The focus was changed, but the control with the previous focus could not be determined. 
Other 


The handle to the control with the previous focus. 


5.12.14. SetGroup 


»»-aBaseDialog^SetGroup(--id--,--4----------- *--)--------------- >< 
+-wantStyle-+ 


Add or remove the group style for the specified control. The group style controls how the user can 
navigate through the dialog using the keyboard. For most dialogs this does not change while the dialog is 
executing. However, in some dialogs the programmer may want to change the navigation depending on 
the options the user selects. 


Arguments: 


The arguments are: 


id 
The resource ID of the dialog control that will gain or lose the group style. 


wantStyle 


A boolean (.true or .false) to indicate whether the dialog control should have or not have the 
group style. True (the default) indicates the control should have the group style and false 
indicates the control should not have the style. 


Return value: 


Negative values indicate the function failed, non-negative values indicate success. 


-4 or less 


The value is the negated Operating System Error code. The absolute value of the return can be 
used to look up the error reason in the Windows documentation. 


The second argument to the method is not a boolean. 
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-2 

There is an (internal) problem with the dialog or the dialog handle. 
-1 

The resource ID of the control is not correct. 
О or greater 


The window style of the dialog control prior to adding or removing the group style. 


5.12.15. SetTabStop 


»»-aBaseDialog^SetTabStop(--id--,--4----------- 4--)------------- >< 
+-wantStyle-+ 


Add or remove the tab stop style for the specified control. When a control has the tabstop style, the user 
can set the focus to the control by using the tab key. When a control does not have this style, the tab key 
will skip over the control. Adding or removing this style during the execution of a dialog allows the 
programmer to alter how the user navigates through the dialog controls. 


Arguments: 


The arguments are: 


id 
The resource ID of the dialog control that will gain or lose the tabstop style. 


wantStyle 


A boolean (.true or .false) to indicate whether the dialog control should have or not have the 
tabstop style. True (the default) indicates the control should have the tabstop style and false 
indicates the control should not have the style. 


Return value: 


Negative values indicate the function failed, non-negative values indicate success. 


-4 or less 


The value is the negated Operating System Error code. The absolute value of the return can be 
used to look up the error reason in the Windows documentation. 


-3 


The second argument to the method is not a boolean. 


-2 


There is an (internal) problem with the dialog or the dialog handle. 
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The resource ID of the control is not correct. 


О or greater 


The window style of the dialog control prior to adding or removing the tabstop style. 


5.12.16. Enableltem 


»»-aBaseDialog^EnableItem(--id--)----------------------------- >< 


The EnableItem method enables the given dialog item. 


Arguments: 


The only argument is: 


id 
The ID of the item 


5.12.17. Disableltem 


»»-aBaseDialog^DisableItem(--id--)---------------------------- >< 


The DisableItem method disables the given dialog item. A disabled dialog item is usually indicated by a 
gray instead of a black title or text; it cannot be changed by the user. 


Arguments: 


The only argument is: 


id 
The ID of the item 


5.12.18. Hideltem 


»»-aBaseDialog^HideItem(--id--)------------------------------- >< 


The Hideltem method makes the given item disappear from the screen and thus unavailable to the user. 
In fact, the item is still in the dialog and you can transfer its data. 
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Arguments: 


The only argument is: 


id 
The ID of the item 


5.12.19. HideltemFast 


»»-aBaseDialog^HideltemFast(--id--)--------------------------- >< 


The HideltemFast method hides an item without redrawing its area. It is similar to the HideItem method, 
but it is faster because the item’s area is not redrawn. The HideItemFast method is used when more than 
one item state is modified. After the operations, you can manually redraw the dialog window, using the 
Update method. 


Arguments: 


The only argument is: 


id 
The ID of the item 


5.12.20. Showltem 


»»-aBaseDialog^ShowItem(--id--)------------------------------- >< 


The ShowItem method makes the given dialog item reappear on the screen. 


Arguments: 


The only argument is: 


id 
The ID of the item 


5.12.21. ShowltemFast 


»»-aBaseDialog^ShowItemFast(--id--)--------------------------- >< 
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The ShowItemFast method shows an item without redrawing its area. It is the counterpart to the 
HideltemFast method. 


5.12.22. HideWindow 


»»-aBaseDialog^HideWindow(--hwnd--)--------------------------- >< 


The HideWindow method hides a whole dialog window or a dialog item. 


Arguments: 


The only argument is: 


hwnd 


A handle to the window or dialog item. Use the GetSelf or GetItem method to get a handle. 


Example: 


The following example gets the window handle of the top dialog (which is not necessarily the 
executing dialog, see the Get method) and hides the whole dialog: 


hwnd = MyDialog^Get 
MyDialog~HideWindow (hwnd) 


5.12.23. HideWindowFast 


>>-aBaseDialog~HideWindowFast (--hwnd--) ----------------------- >< 


The HideWindowFast method is similar to the HideWindow method, but it is faster because the 
window’s or item’s area is not redrawn. The HideWindowFast method is used when more than one state 
is modified. After the operations, you can manually redraw the dialog window, using the Update method. 


Arguments: 


The only argument is: 


hwnd 


A handle to the window or dialog item 


5.12.24. ShowWindow 


»»-aBaseDialog^ShowWindow(--hwnd--)--------------------------- >< 


ooRexx OODialog Reference Version 4.0.0 165 


Chapter 5. BaseDialog Class 


The ShowWindow method shows the window or item again. 


Arguments: 


The only argument is: 


hwnd 


The handle of a window or an item 


5.12.25. ShowWindowFast 


>>-aBaseDialog~ ShowWindowFast (--hwnd--)----------------------- >< 


The ShowWindowFast method is the counterpart to the HideWindowFast method. 


5.12.26. SetWindowRect 


»»-aBaseDialog^SetWindowRect (--hwnd--,--x--,--y--,--width--,--height--» 
a E sa aa >< 
| +---------------- + | 
| ү | | 
+-,--'"'----+-NOMOVE-----+-4+--"-+ 
+-NOSIZE----- + 


+-HIDEWINDOW-+ 
+-SHOWWINDOW-+ 
+-NOREDRAW---+ 


The SetWindowRect method sets new coordinates for a specific window. 


Arguments: 


The arguments are: 


hwnd 


The handle to the dialog that is to be repositioned. 


х,у 


The new position of the upper left corner, in screen pixels. 


width 


The new width of the window, in screen pixels. 
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height 


The new height of the window, in screen pixels. 


showOptions 


This argument can be one or more of the following keywords, separated by blanks: 
NOMOVE 
The upper left position of the window has not changed. 


NOSIZE 


The size of the window has not changed. 


HIDEWINDOW 


The window is to be made invisible. 


SHOWWINDOW 


The window is to be made visible. 


NOREDRAW 


The window is to be repositioned without redrawing it. 


Return value: 


Repositioning was successful. 


Repositioning failed. 


5.12.27. RedrawWindow 


»»-aBaseDialog^RedrawWindow(--hwnd--)------------------------- >< 


The RedrawWindow method redraws a specific dialog. 


Arguments: 


The only argument is: 


hwnd 


The handle to the dialog that is to be redrawn. 
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Return value: 


Redrawing was successful. 


Redrawing failed. 


5.12.28. Resizeltem 


»»-aBaseDialog^ResizeItem(--id--,--width--,--height--4------------------------- +--)->< 
+-,--"--+-HIDEWINDOW-+--"-+ 
+-SHOWWINDOW-+ 
+-NOREDRAW---+ 


The ResizeItem method changes the size of a dialog item. 


Arguments: 


The arguments are: 
id 

The ID of the dialog item you want to resize 
width, height 

The new size in dialog units 


showOptions 


This argument can be one of the following keywords: 


HIDEWINDOW 


Hides the item 


SHOWWINDOW 


Shows the item 


NOREDRAW 


Resizes the item without updating the display. Use the Update method to manually update 
the display. 
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Example: 
The following example resizes a dialog item: 


MyDialog^Resizeltem(123, 40, 30, "SHOWWINDOW") 


5.12.29. Moveltem 


»»-aBaseDialog^Moveltem(--id--,--xPos--,--yPos--4------------------------- +--)->< 
++, --"--+-HIDEWINDOW-+--"-+ 
+-SHOWWINDOW-+ 
+-NOREDRAW---+ 


The Moveltem method moves a dialog item to another position within the dialog window. 


Arguments: 


The arguments are: 
id 
The ID of the dialog item you want to move 


XPos, yPos 


The new position in dialog units relative to the dialog window 


showOptions 


This argument can be one of the following keywords: 


HIDEWINDOW 
Hides the dialog 


SHOWWINDOW 
Shows the dialog 


NOREDRAW 


Moves the dialog item without updating the display. Use the Update method to manually 
update the display. 


5.12.30. Center 


»»-aBaseDialog^Center(--"--4-HIDEWINDOW-4--"--)--------------- >< 
*-SHOWWINDOW-- 
*-NOREDRAW---- 
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Arguments: 


The only argument can be one of: 
HIDEWINDOW 
Hides the dialog 


SHOWWINDOW 
Shows the dialog 


NOREDRAW 


Center the dialog without updating the display. Use the Update method to manually update the 
display. 


5.12.31. assignWindow (deprecated) 


Note: This method is deprecated and will not be supported in future vesions of ooDialog. The 
method will always return 0, the connection failed. To work with a dialog or dialog control object, 
construct the proper ooDialog object. To control a window not owned by your program use the fina() 
method of the WindowsManger. The WindowsManager class is part of the WinSystm.cls package. 


5.12.32. SetWindowTitle 


»»-aBaseDialog^SetWindowTitle(--hwnd--,--aString--)----------- >< 


The SetWindowTitle method changes the title of a window. 


Arguments: 


The arguments are: 


hwnd 


The handle of the window whose title you want to change 


aString 


The new title text 
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5.12.33. FileViewer Example Program 


The FileViewer program is a complete working program that uses many of the methods of the base 
dialog. Portions of this program are presented as examples in the documentation for these methods. The 
complete program is shown here as a reference to how the code snippets all fit together. 


The documentation for the individual methods used in the program has additional commentary that will 
help in understanding how the program works. 


* Init: This program uses a header file, fileView.h to define symbolic IDs for the dialog controls. The 
name of the file is one of the arguments used to create a new instance of a dialog object. (As in all 
Rexx classes, the arguments used in new are passed on to the init method of the class.) 


* Execute: Two dialogs are created in the example. The first dialog allows the user to enter the name of a 
file to view. Then the file itself is displayed in a second dialog. Each dialog uses a different application 
icon. The Execute method documentation has more detail on the application icon. 


InitDialog This method is called after the underlying Windows dialog has been created, but before it is 
shown on the screen. In the viewer dialog the Init method is overridden and the text of the read-only 
multi-line edit control is set to the contents of the file. In both dialogs, this method is used to get and 
save a reference to the edit control of the dialog. 


* DisableItem: When the user clicks the "View File" button, the button is disabled until the user is 
finished viewing the file. When a button is disabled it can not be clicked by the user. 


* Enableltem: When the user closes the secondary viewer dialog, the "View File" button is enabled so 
the user can choose to view another file. 


* PopupAsChild: The viewer dialog is executed using this method so that both dialogs run 
independently, both dialogs stay enabled. The HIDE keyword is used for the show argument. This 
creates the dialog as invisible and prevents unnecessary screen flicker. 


* Maximize: Note that there is a 100 millisecond sleep right before the Maximize method is invoked. 
This allows Windows to finish creating the dialog. The InitDialog method will have already finished 
executing and the contents of the file are loaded into the multi-line edit control. Then, Maximize 
resizes the dialog to take up the whole screen and shows it. The dialog appears on the user’s screen, 
with the file displayed, in one screen drawing. This reduces the flicker on the screen. 


* Minimize: When the viewer dialog is maximized, the main dialog is minimized to the task bar. 


* InitAutoDetection: Because the contents of the file are loaded into the multi-line edit control during 
InitDialog, auto detection must be turned off. Otherwise, after InitDialog finishes executing, auto 
detection would set the empty string as the text for the control. The program overrides this method to 
turn auto detection off. 


* NoAutoDetection: Used in turning auto detection off. 


* ConnectResize: When the viewer dialog is resized, the onSize method is invoked. The size of the 
multi-line edit control is then changed so it completely takes up the client area of the dialog. (The 
client area of a window is where all the child windows are drawn. In this case the edit control is the 
only child window.) Since the dialog is not resizeable by the user (it does not have a sizing border) the 
only time the size can change is when the dialog is maximized, minimized, or restored. 


* Hideltem: The edit control in the viewer dialog is created invisible. Again, this helps reduce flicker. 


* Getltem: The window handle of the edit control is obtained by this method ... 
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* GetClientRect: ... then the size of the client area of the viewer dialog is obtained using this method. 
Then .. 


* SetWindowRect: ... the size of the edit control window is set using to the size of the dialog's client 
area. 


* ShowlItem: The ShowItem method is used to make the edit control visible when the dialog is initially 
shown. 


* IsMinimized: When the viewer dialog is closed, this method checks to see if the main dialog is still 
minimized. Since the dialogs run independently the user may have already restored this dialog. 


* Restore: If the main dialog is still minimized, then this method restores it to its normal position. 


/* fileView.h Simple symbolic ID definitions */ 


#define IDD_DIALOG1 100 
#define IDC_ST_TYPE 105 
#define IDC_ENTRYLINE 106 
#define IDC_MULTILINE 107 
#define IDC_PB_VIEW 111 


/* FileViewer.rex Simple Dialog to view files full screen */ 


dlg = .FileView~new( , "fileView.h") 

if dlg~initCode = 0 then до 
dlg~createCenter(170, 90, "The File Viewer Dialog", "VISIBLE MAXIMIZEBOX MINIMIZEBOX") 
dlg^Execute("SHOWTOP", IDI_DLG_OOREXX) 
dlg^Deinstall 

end 


-- End of entry point. 
::requires "QODWin32.cls" 


::class FileView subclass UserDialog inherit AdvancedControls 
::method defineDialog 


self^addText(10, 25, 150, 10, " Enter the name of a file to view:", "", IDC ST TYPE) 
self^addEntryLine(IDC ENTRYLINE, , 10, 35, 150, 10, "AUTOSCROLLH") 


-- When the view button is pushed, another dialog will show the file. 
self^addButton(IDC PB VIEW, 10, 55, 35, 15, "View File", onView, "DEFAULT GROUP") 
self^addButton(IDOK, 130, 55, 35, 15, "Quit") 

::method initDialog 
expose editCntrl 


editCntrl = self^getEditControl(IDC ENTRYLINE) 


::method onView 
expose viewDlg editCntrl 


fileName = editCntrl^getText 
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viewDlg = .Viewer^new( , "fileView.h", self, fileName) 
if viewDlg^initCode = 0 then do 
self^disableItem(IDC. PB VIEW) 


viewDlg^create(30, 30, 170, 180, "Viewer", "MAXIMIZEBOX MINIMIZEBOX") 
viewDlg^popUpAsChild(self, "HIDE", , IDI_DLG_APPICON) 


-- The underlying Windows dialog has to be created before it can be maximized. 
j = msSleep(100) 


у1еи01р maximize 
self~minimize 
end 


::class ’Viewer’ subclass UserDialog inherit AdvancedControls 


::method init 
expose parent filename 
use arg data, header, parent, fileName 
forward class (super) 


::method initAutoDetection 
self~noAutoDetection 


::method defineDialog 
expose wasMinimized 


wasMinimized = .false 

style = "VSCROLL HSCROLL MULTILINE READONLY" 
self~addEntryLine(IDC_MULTILINE, "cEntry", 0, 0, 170, 180, style) 
self^connectResize("onSize") 


::method initDialog 
expose editControl fileName isHidden 


self~hideItem(IDC_MULTILINE) 
isHidden = .true 


editControl = self~getEditControl (IDC_MULTILINE) 


fÜbj = .stream^new(fileName) 

text = fÜbj^charin(1, f0bj~chars) 

f0bj~ close 

if text == "" then text =" No file " 


editControl^setText (text) 
::method onSize 

expose wasMinimized 

use arg sizeEvent sizeInfo 


if sizeEvent = 1 then wasMinimized = .true 


if sizeEvent = 0 | sizeEvent = 2 then do 
if \ wasMinimized then self^resizeEditControl 
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wasMinimized = .false 
end 


::method resizeEditControl 
expose editControl isHidden 


hWnd = self~getItem(IDC_MULTILINE) 
parse value self^getClientRect with wx wy wcx wcy 


self~setWindowRect (hWnd, 0, 0, wcx, ысу) 


if isHidden then do 
self~showItem(IDC_MULTIINE) 
isHidden = .false 

end 


::method cancel 
expose parent 
parent ~ enableItem(IDC_PB_VIEW) 
if parent^isMinimized then parent^restore 
return self^cancel:super 


5.13. Window Draw Methods 


The methods listed below are used to draw, redraw, and clear window areas. 


5.13.1. DrawButton 


»»-aBaseDialog^DrawButton(--id--)--------------------- 


The DrawButton method draws the given button. 


Arguments: 


The only argument is: 


id 
The ID of the button 


5.13.2. RedrawRect 
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»»-aBaseDialog^RedrawRect(--4------4--,--left--,--top--,--right--,--bottom--,--4---------- 
+--)->< 

+-hwnd-+ +-erasebkg- 
+ 


The RedrawRect method immediately redraws a rectangle within the client area of a dialog. You can 
specify whether the background of the dialog is to be erased before redrawing. 


Arguments: 


The arguments are: 


hwnd 


The handle to the dialog in which parts of the client area are to be redrawn. See Get or GetItem 
for information on how to get a window handle. If you omit this argument, the handle of the 
dialog instance is used. 


left, top 


The upper left corner of the rectangle relative to the client area, in screen pixels. 


right, bottom 


The lower right corner of the rectangle relative to the client area, in screen pixels. 


erasebkg 


If this argument is 1 or O, the background of the dialog is erased before redrawing. The default 
is 0. 


Return value: 


Redrawing was successful. 


Redrawing failed. 


5.13.3. RedrawButton 


»»-aBaseDialog^RedrawButton(--id--4------------- *--)---------- >< 
*-,--erasebkg--* 


The RedrawButton method redraws the given button. 
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Arguments: 
The arguments are: 
id 
The ID of the button 


erasebkg 


Determines whether (1) or not (0) the background of the drawing area should be erased before 
redrawing. The default is 0. 


5.13.4. RedrawWindowRect 


»»-aBaseDialog^RedrawWindowRect--4----------------------------- +-->< 
*-(--hwnd--*------------- +--)-+ 
+-,--erasebkg-+ 


The RedrawWindowRect method redraws the given window rectangle. 


Arguments: 


The arguments are: 


hwnd 


The handle to the window. See Get or Сеет for information on how to get a window handle. 
If you omit this argument, the handle of the dialog instance is used. 


erasebkg 


Determines whether (1) or not (0) the background of the drawing area should be erased before 
redrawing. The default is 0. 


5.13.5. ClearRect 


>>-aBaseDialog~ClearRect (--hwnd--,--left--,--top--,--right--,--bottom--)--»« 


The ClearRect method clears the given rectangle of a window. The values are in pixels. 
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Arguments: 


The arguments are: 


hwnd 


The handle of the window. See GetSelf or GetItem for information on obtaining a window 
handle. 


left 


The horizontal value of the upper-left corner of the rectangle 


top 


The vertical value of the upper left corner 
right 

The horizontal value of the lower right corner 
bottom 


The vertical value of the lower right corner 


Example: 
The following example clears a rectangle of the size 20 by 20: 


hwnd-MyDialog^GetSelf 
MyDialog^ClearRect(hwnd, 2, 4, 22, 24) 


5.13.6. ClearButtonRect 


»»-aBaseDialog^ClearButtonRect(--id--)------------------------ >< 


The ClearButtonRect method erases the draw area of the given button. 


Arguments: 


The only argument is: 


id 
The ID of the push button 


5.13.7. ClearWindowRect 


>>-aBaseDialog~ClearWindowRect (--hwnd--)---------------------- >< 
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The ClearWindowRect method erases the draw area of the given window. 


Arguments: 


The only argument is: 


hwnd 


The handle of the window. See GetSelf, Get, or GetItem for some methods to get a window 
handle. 


Example: 


The following example gets the window handle of a dialog control with resource ID of 211 and then 
clears the dialog control window: 


hwnd = MyDialog~GetItem(211) 
MyDialog^ClearWindowRect (hwnd) 


5.14. Bitmap Methods 


The methods listed below deal with bitmaps. 


5.14.1. ChangeBitmapButton 


»»-aBaseDialog^ChangeBitmapButton(--id--,--bmpNormal----------------------- > 
>--+------------------------------------------------------------------—-—- +--> 
че DIIPPOCUSCO нат Sa ee +-+ 
+=, Бпрбейесъей--+#-----------------+---------- +-+ 

+=, БшррівабТеа==+==============- +-+ 


+-,styleOptions-+ 


»--)---------------------------------------------------------------------- >< 


The ChangeBitmapButton method changes the bitmaps of a bitmap button. 


Arguments: 
The arguments are the same as for ConnectBitmapButton, except for the first argument 
(msgToRaise), which is skipped in this method. 

Example: 
The following example replaces the current bitmap with a new bitmap: 


MyDialog~ChangeBitmapButton(501, "NewBB.bmp") 
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5.14.2. GetBitmapSizeX 
»»-aBaseDialog^GetBitmapSizeX(--id--)------------------------- >< 
The GetBitmapSizeX method returns the horizontal bitmap extension. 


Arguments: 


The only argument is: 


id 
The ID of the bitmap button 


5.14.3. GetBitmapSizeY 
»»-aBaseDialog^GetBitmapSizeY(--id--)------------------------- >< 
The GetBitmapSizeY method returns the vertical bitmap extension. 


Arguments: 


The only argument is: 


id 
The ID of the bitmap button 


5.14.4. DrawBitmap 


>>-aBaseDialog~DrawBitmap (--+------+-- , --id---------------------- > 
+-hwnd-+ 
>--+---------------------------------------------------------— +--> 
+-,--рх--,--ру--+---------------------------------------- +-+ 
+=,==вгсх-=,==Втбу==ф—-===з==-==-=——ашелеше +=+ 
+-,--х1еп--,--у1еп-+ 
»--)------------------------------------------------------------ >< 


The DrawBitmap method draws the bitmap of a button. You can also use this method to move a bitmap 


or a part of it. 
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Arguments: 


The arguments are: 


hwnd 


The handle to the window. If this argument is omitted, the handle for the button is used 
automatically. 


The ID of the button that has the owner-draw option set 


PX, py 
The upper-left corner of the target space within the button (default is 0) 


SICX, згсу 


The upper-left corner within the bitmap (default is 0) 


xlen, yLen 


The extension of the bitmap or a part of it (default is the whole bitmap) 


5.14.5. ScrollBitmapFromTo 


»»-aBaseDialog^ScrollBitmapFromTo(--id--,--fromX--,--fromY--,--toX--,--toY--,--» 
»--stepX--,--stepY--,--delay--,--displace--)------------------ >< 


The ScrollBitmapFromTo method scrolls a bitmap from one position to another within an owner-drawn 
button. 


Arguments: 
The arguments are: 
id 
The ID of the button 


fromX, fromY 


The starting position 


toX, toY 


The target position 


stepX, stepY 


The width of one step 
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delay 


The time in milliseconds this method waits after each move before doing the next move. This 
determines the speed at which the bitmap moves. 


displace 


If set to 1 the internal position of the bitmap (bitmap displacement) is updated after each 
incremental move. DisplaceBitmap is called after each step to adjust the bitmap position. If the 
dialog is redrawn, the bitmap is shown at the correct position, but the drawing is slower. 


5.14.6. TiledBackgroundBitmap 


»»-aBaseDialog^TiledBackgroundBitmap(--bmpFilename--)--------- >< 


The TiledBackgroundBitmap method sets a bitmap as the background brush (Windows NT® only). If the 
bitmap size is less than the size of the background, the bitmap is drawn repetitively. 


Arguments: 


The only argument is: 


bmpFilename 


The name of a bitmap file 


5.14.7. BackgroundBitmap 


»»-aBaseDialog^BackgroundBitmap(--bmpFilename------------------- ? 
>--+------------+ в) 9 Sn ssa >< 
+-,--"USEPAL"-+ 


The BackgroundBitmap method sets a bitmap as the dialog’s background picture. 


Arguments: 


The arguments are: 
bmpFilename 
The name of a bitmap file 


option 


Set the last argument to USEPAL if you want to use the color palette of the bitmap. See 
ConnectBitmapButton for more information. 
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5.14.8. DisplaceBitmap 
»»-aBaseDialog^DisplaceBitmap(--id--,--x--,--y--)------------- >< 
The DisplaceBitmap method sets the position of a bitmap within a button. 


Arguments: 


The arguments are: 


id 
The ID of a button 
x 
The horizontal displacement in screen pixels. A negative value can be used. 
y 
The vertical displacement (negative allowed) 
Example: 


The following example moves the bitmap within a button four screen pixels to the right and three 
pixels upward: 


MyBaseDialog^DisplaceBitmap(244, 4, -3) 


5.14.9. GetBmpDisplacement 


>>-aBaseDialog~GetBmpDisplacement (--id--)--------------------- >< 


The GetBmpDisplacement method gets the position of a bitmap within a button. 


Arguments: 


The only argument is: 


id 
The ID of the button 


Example: 
The following example shows how to use the GetButtonRect and GetBmpDisplacement methods: 


bRect = MyBaseDialog^GetButtonRect (244) 

parse var bRect left top right bottom 

bmpPos = MyBaseDialog~GetBmpDisplacement (244) 
parse var bmpPos x y 
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5.15. Device Context Methods 


The methods listed below are used to retrieve and release a device context. 


A device context is associated with a window, a dialog, or a push button, and is a drawing area managed 
by a window. A device context stores information about the graphic objects (bitmaps, lines, pixels, ...) 
that are displayed and the tools (pen, brush, font, ...) that are used to display them. 


5.15.1. GetWindowDC 


»»-aBaseDialog^GetWindowDC(--hwnd--)-------------------------- >< 


The GetWindowDC method returns the device context of a window. Do not forget to free the device 
context after you have completed the operations (see FreeWindowDC). 


Arguments: 


The only argument is: 


hwnd 


The handle of the window 


5.15.2. GetButtonDC 


»»-aBaseDialog^GetButtonDC(--id--)---------------------------- >< 


The GetButtonDC method returns the device context of a button. Do not forget to free the device context 
after you have completed the operations (see FreeButtonDC). 


Arguments: 


The only argument is: 


id 
The ID of the button 


5.15.3. FreeWindowDC 


»»-aBaseDialog^FreeWindowDC(--hwnd--,--dc--)------------------ >< 


The FreeWindowDC method frees the device context of a window. 
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Arguments: 
The arguments are: 
hwnd 
The window handle 


dc 


The device context previously received by the GetWindowDC method 


5.15.4. FreeButtonDC 


»»-aBaseDialog^FreeButtonDC(--id--,--dc--)-------------------- >< 


The FreeButtonDC method releases the device context of a button. 


Arguments: 
The arguments are: 
id 
The ID of the button 


dc 


The device context previously received by the GetButtonDC method 


5.16. Text Methods 


The following methods are used to display text dynamically in a window area and to modify the state of 
a device context. See GetWindowDC, GetDC, and GetButtonDC for information on how to retrieve a 
device context. 


5.16.1. Write 


»»-aBaseDialog^Write(--xPos--,--yPos--,--text---------------------------------- ? 
B-—R------------------------------------------------------------------------ +--> 
| *-"SYSTEM"-- | 
4-,------------ 4-—R--------------------------------------------------- +-+ 
+-fontName-+ | *-10------- * | 

+-,--+---------- +--+------------------------------ +-+ 
+-fontSize-+ | +----------------- + | 
| V +-OPAQUE------ + | | 
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+-,--"----+-THIN--------+-+--"-+ 
+-EXTRALIGHT--+ 
*-LIGHT------- + 
*-MEDIUM------ + 


+-SEMIBOLD----+ 
+-EXTRABOLD---+ 


+-BOLD-------- + 
*-HEAVY------- * 
+-UNDERLINE---+ 
*-ITALIC------ * 


*-STRIKEOUT----4 

+-TRANSPARENT-+ 

*-CLIENT------ * 
»--)-------------------------------------------------------------------------- >< 


The Write method enables you to write text to the dialog in the given font and size, to the given position. 
This method does not take a handle or an ID; it always writes to the dialog window. 


Arguments: 


See WriteToWindow for a description of the other arguments. 


5.16.2. ScrollText 


»»-aBaseDialog^ScrollText (--hwnd-- ,--text-- ,--+---------- pomi n +==> 
+-fontName-+ +-fontSize-+ 
>--,--+-------------------------- +------------------------------------------- > 
| +---------------- + 
| V | | 
+-----+-ТНШ-------+-+--"-+ 
+-EXTRALIGHT-+ 
+-LIGHT------ + 
+-MEDIUM----- + 


+-SEMIBOLD---+ 
+-EXTRABOLD--+ 


+-BOLD------- + 
*-HEAVY------ * 
+-UNDERLINE--+ 
+-ITALIC----- + 


+-STRIKEOQUT--+ 


»--,--displaceY--,--step--,--sleep--,--color--)----------------------------- >< 


The ScrollText method scrolls text in a window with the given size, font, and color. The text is scrolled 
from right to left. If the method is started concurrently, call it a second time to stop scrolling. 
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Arguments: 


The arguments are: 


hwnd 


The handle of the window in which the text is scrolled 


text 


A text string that is scrolled 


displaceY 


The vertical displacement of the text relative to the top of the window’s client area (default 0) 


step 


The size of one step in screen pixels (default 4) 


sleep 
The time in milliseconds that the program waits after each movement (default 10). This 
determines the speed. 

color 
The color of the text (default 0, black) 


See WriteToWindow for a description of the other arguments. 


Example: 


The following example scrolls the string "Hello world!" from left to right within the given window. 
The text is located two pixels below the top of the client area, one move is 3 screen pixels, and the 
delay time after each movement is 15 ms. 


MyDialog~ScrollText (hwnd, "Hello world!", , , , 2, 3, 15) 


Note: Only one sleep interval can be set for multiple scrolling texts within one process. All scrolling 
text in one process is synchronized with the first given interval. 


5.16.3. ScrolllnButton 


»»-aBaseDialog^ScrollInButton(--id--,--text--,--4---------- pom cA 
+-fontName-+ 


>--+---------- +--,--+-------------------------- +---------------- > 
+-fontSize-+ | 4---------------- * | 
| V | | 
+-"----+-THIN-------+-+--"-+ 
+-EXTRALIGHT-+ 
*-LIGHT------ + 
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+-SEMIBOLD---+ 
+-EXTRABOLD--+ 


*-BOLD------- * 
*-HEAVY------ * 
+-UNDERLINE--+ 
+-ITALIC----- + 


+-STRIKEOUT--+ 
»--,--displaceY--,--step--,--sleep--,--color--)--------------- >< 


The ScrollInButton method scrolls text within a button. It is similar to the ScrollText method, except that 
you have to pass an ID instead of a window handle. 


5.16.4. ScrollButton 


>>-aBaseDialog~Scrol1Button(--id-- ,--xPos-- ,--yPos-- ,--left-- ,--top--> 


»--,--right--,--bottom--)------------------------------------- >< 


The ScrollButton method moves the rectangle within a button. It is used to move bitmaps within buttons. 


Arguments: 
The arguments are: 
id 
The ID of the button 


xPos, yPos 


The new position of the rectangle (in pixels) 


left, top, right, bottom 


The extension of the rectangle 


5.16.5. SetltemFont 


+-1-------- + 
>>--aBaseDialog~SetItemFont (--id-- ,--fonthandle-- ,--+ ========55 +--)-->< 
+--redraw--+ 


The SetItemFont method changes the font for a particular dialog item. 
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The best place to call this method is within InitDialog. If the font is no longer needed, for instance, when 
the dialog is closed or another font has been assigned to the dialog item, you should free the font 
resource by calling DeleteFont. A good place to do this is the Leaving method. 


Arguments: 


The arguments are: 


id 
The ID of the dialog item. 


fonthandle 


The handle returned by createFontEx. 


redraw 


Do not redraw the item. 


Redraw the item, which is the default. 


Example: 
The following example sets a 12-point Arial font for item 101. 


::method InitDialog 


hFont-self^createFontEx("Arial",12) 
self^SetItemFont(101,hFont,0) 


5.16.6. GetTextSize (deprecated) 


Note: This method is deprecated. It is maintained for compatibility to versions of ooDialog previous 
to 4.0.0. It’s functionality is replaced by the getTextSizeDlg() method. Do not use this method in new 
code. Try to migrate existing code to use the getTextSizepigO method. This method may not exist in 
future versions of ooDialog. 


This method never worked correctly, the previous documentation for this method was incorrect and / 
or misleading. That has been fixed with with getTextSizeDlg(). The documentation for 
getTextSizeDlg() correctly explains how the method works and, hopefully, is not misleading. 
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5.17. Animated Buttons 


The methods listed below work with animated buttons. 


5.17.1. AddAutoStartMethod 


»»-aBaseDialog^AddAutoStartMethod(--4--------- *--,--MethodName--4--------------- +--) ->< 
+-InClass-+ +-,--Parameters-+ 


The AddAutoStartMethod method adds a method name and parameters to a special internal queue. All 
methods in this queue will be started automatically and run concurrently when the dialog is executed. 
The given method (MethodName) in the given class (InClass) is started concurrently with the dialog 
when the dialog is activated using the Execute or ExecuteAsync method. This is useful for processing 
animated buttons. 


Arguments: 


The arguments are: 


InClass 


The class where the method is defined. If this argument is omitted, the method is assumed to be 
defined in the dialog class. 


MethodName 


The name of the method 


Parameters 


All parameters that are passed to this method 


Example: 


The following example installs the ExecuteB method of the MyAnimatedButton class so that it is 
processed concurrently with the dialog execution: 


MyDialog^AddAutoStartMethod("MyAnimatedButton", "ExecuteB") 


::class MyAnimatedButton 
::method ExecuteB 


5.17.2. ConnectAnimatedButton 


>>-aBaseDialog” Connect AnimatedButton(--id, --+------------ demam 
+-msgToRaise-+ 
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> e f--,.--bmpProm--,--t-------t--,--moveX——,--moveY--,--2 
+-AutoClass-+ +-bmpTo-+ 

>--+-------+--,--+-------+--,--йе1ау--,--+------+--,--+------+--)->< 
+-sizeX-+ +-sizeY-+ +-xNow-+ +-yNow-+ 


The ConnectAnimatedButton method installs an animated button and runs it concurrently with the main 
activity. 


Arguments: 


The arguments are: 


id 
The ID of the button 

msgToRaise 
The name of a method within the same class. This method is called each time the button is 
clicked. 

AutoClass 


The class that controls the animation (default is AnimatedButton Class) 


bmpFrom 


The ID of the first bitmap in the animation sequence within a binary resource. It can also be the 
name of an array stored in the оса! directory containing handles of bitmaps to be animated 
and bmpTo is omitted. See LoadBitmap for how to get bitmap handles. The array starts at 
index 1. 

bmpTo 


The ID of the last bitmap in the animation sequence within a binary resource. If omitted, 
bmpFrom is expected to be the name of an array stored in .local that holds the bitmap handles 
of the bitmaps that are to be animated. 


moveX, move Y 


Size of one move (in pixels) 


sizeX, sizeY 


Size of the bitmaps (if omitted, the size of the bitmaps is retrieved) 


delay 


The time in milliseconds the method waits after each move 


XnOW, ynow 


The starting position of the bitmap 
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Example: 


The following example defines and runs an animated button. The example loads ten bitmaps 
("anibmpl.bmp" to "anibmp10.bmp") into memory and stores them into the array "My.Bitmaps" 
that is stored in the .local directory. The name "My.Bitmaps" is specified as the bmpfrom and bmpto 
is omitted. After the dialog execution the bitmaps are removed from memory again. The sample also 
uses a different animation class (".MyAnimation") which subclasses from .AnimatedButton and 
overrides method HitRight which plays a tune each time the animated bitmap hits the right border. 
/* store array in .local */ 
.Local["My.Bitmaps"] = .array^new(10) 
/* load 10 bitmaps into .local array */ 
do i- 1 to 10 
.Local["My.Bitmaps"][i] = Dialog^LoadBitmap("anibmp"i".bmp") 
/* you could also use .My.Bitmaps[i] = ... */ 
end 


/* connect bitmap sequence and .MyAnimated class with button IDANI */ 
Dialog^ConnectAnimatedButton("IDANI", ,.MyAnimation,"My.Bitmaps", ,1,1, , ,100) 


Dialog^Execute 


/* Free the bitmap previously loaded */ 

do bmp over .Local["My.Bitmaps"] /* You could also use do bmp over .My.Bitmaps */ 
Dialog^RemoveBitmap (bmp) 

end 

::class MyAnimation subclass AnimatedButton 

/* play sound.wav whenever the bitmap hits the right border */ 

::method HitRight 


ret - Play("sound.wav", yes) 
return self^super:hitright 


5.18. Menu Methods 


The methods listed below manipulate a menu connected to the dialog. 


5.18.1. ConnectMenultem 


»»-aBaseDialog^ConnectMenultem(--id--,--msgToRaise--)--------- >< 


The ConnectMenultem method is called to connect a menu item selection with a method. 
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Arguments: 


The arguments are: 


id 
The ID of the menu item. 


msgToRaise 


The name of the method that is to be called. 


Example: 
See ConnectButton. 


Do not use one of the menu item methods below, prior to the SetMenu method. If you call one of these 
methods before SetMenu has been called, the intended action will not be processed and the return code is 
unpredictable. 


5.18.2. EnableMenultem 


»»-aBaseDialog^EnableMenuItem(--id--)------------------------- >< 


The EnableMenultem method is called to enable a menu item. 


Arguments: 


The only argument is: 


id 


The ID of the menu item to be enabled. 


5.18.3. DisableMenultem 


>>-aBaseDialog~DisableMenultem(--id--) ------------------------ >< 


The DisableMenultem method is called to disable a menu item. 


Arguments: 


The only argument is: 


id 


The ID of the menu item to be disabled. 


192 ooRexx OODialog Reference Version 4.0.0 


Chapter 5. BaseDialog Class 


5.18.4. CheckMenultem 


>>-aBaseDialog~ CheckMenuItem(--id--) -------------------------- >< 


The CheckMenultem method is called to set the check mark for a menu item. 


Arguments: 


The only argument is: 


id 


The ID of the menu item to be checked. 


5.18.5. UncheckMenultem 


»»-aBaseDialog^UncheckMenultem(--id--)------------------------ >< 


The UncheckMenultem method is called to remove the check mark from a menu item. 


Arguments: 


The only argument is: 


id 


The ID of the menu item to be unchecked. 


5.18.6. GrayMenultem 


>>-aBaseDialog~GrayMenuItem(--id--) --------------------------- >< 


The GrayMenultem method is called to disable a menu item. The menu item is grayed. 


EnableMenultem is used to reset the grayed state. 


Arguments: 


The only argument is: 


id 


The ID of the menu item to be grayed. 


ooRexx OODialog Reference Version 4.0.0 193 


Chapter 5. BaseDialog Class 


5.18.7. SetMenultemRadio 


»»-aBaseDialog^SetMenultemRadio(--idstart--,--idend--,--idset--)»« 


The SetMenultemRadio method is used to change the selection for a radio button menu group. 


Arguments: 


The arguments are: 
idstart 
The ID of the first menu item in the group. 


idend 


The ID of the last menu item in the group. 


idset 


The ID of the menu item that is to be selected. 


Example: 


The following example shows how to change the selection within a radio button group. Menu item 
102 gets the radio button. 


self^SetMenuItemRadio(101, 105, 102) 


5.18.8. GetMenultemState 


»»-aBaseDialog^GetMenultemState(--id--)----------------------- >< 


The GetMenultemState method returns the state of a given menu item 


Arguments: 


The only argument is: 


id 


The ID of the menu item whose state is of interest. 


Return values: 


CHECKED DISABLED GRAYED HIGHLIGHTED 
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5.19. Debugging Method 


The following method displays the internal setting of the dialog administration table. 


5.19.1. Dump 


The Dump method displays the internal settings of the dialog administration table. This method can be 
helpful for debugging OODialog programs. 


»»-Dump(--4------------- 4*--)---------------------------------- >< 
+-dialogadmin-+ 


Argument: 


The only argument is: 


dialogadmin 


A pointer to a particular dialog administration record. If you specify this argument, you get 
detailed information on this record. If you omit this argument, all administration records (one 
for each dialog of the active process) are listed. 


Return value: 


This method does not return a value. 
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The DialogControl class provides methods that are common to all dialog controls. It is a generic class 
that serves as a superclass to all dialog control specific classes. In the graphical user interface (GUI) for 
the Windows operating system both dialogs and dialog controls are windows. Therefore, many of the 
methods of the DialogControl class are the same as the methods of the ooDialog dialog classes. These 
are the methods that are common to all windows, whether they are dialog windows or dialog control 
windows. 


In the Windows GUI all windows are created with a set of window styles. Dialog control windows are 
created using styles that are common to all windows, (for example the visible style,) and styles specific 
to the dialog control itself, (for example the multi-line style of the EditControl class.) In general the 
styles of a control fall into three categories: Styles that can only be set when the control is created and 
then can not be changed afterwards. Styles that can be changed after control creation by sending 
messages to the control. And, styles that can be changed after the control is created by accessing the 
control window directly. 


The ooDialog programmer chooses the window styles for dialog controls when he defines the dialog, 
either by using a resource editor for dialogs defined with resource scripts or binary compiled resources, 
or by using the Add... Methods for a user dialog. After the dialog control has been created, the individual 
dialog control classes provide methods to change those styles that can be changed, either by sending the 
proper message to the control or by accessing the control window directly. 


Requires: 
The DialogControl class requires the class definition file oodwin32.cls: 


::requires oodwin32.cls 


Attributes: 


Instances of the DialogControl class have the following attributes: 


FactorX 


The horizontal size of one dialog unit, in pixels. 


FactorY 


The vertical size of one dialog unit, in pixels. 


SizeX 


The width of the dialog control, in dialog units, when the Rexx object that represents the 
control is created. 


Note: The SizeX attribute is not changed by ooDialog after the object is instantiated. If the 
programmer resizes the dialog control manually, and requires that the value of the attribute be 
correct, then the programmer would need to update the value herself. 


SizeY 


The height of the dialog control, in dialog units, when the Rexx object that represents the 
control is created. 
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Note: The SizeY attribute is not changed by ooDialog after the object is instantiated. If the 
programmer resizes the dialog control manually, the programmer would also need to update 
the value of this attribute herself, if she requires that the value remain correct. 


Methods: 


Instances of the DialogControl class implement the methods listed in the following DialogControl 


Instance Methods table. 


Table 6-1. DialogControl Instance Methods 









































Method... ..оп page 
AbsRect2LogRect AbsRect2LogRect 
AssignFocus AssignFocus 
CaptureMouse CaptureMouse 
Clear Clear 

ClearRect ClearRect 
ClientToScreen ClientToScreen 
ConnectFKeyPress ConnectFKeyPress 
ConnectKeyPress ConnectKeyPress 
CreateBrush CreateBrush 
createFont createFont 
CreateFontEx CreateFontEx 
CreatePen CreatePen 





Cursor_AppStarting 


Cursor_AppStarting 





Cursor_Arrow 


Cursor_Arrow 





Cursor_Cross 


Cursor_Cross 





Cursor_No 


Cursor_No 





CursorPos 


CursorPos 





Cursor_Wait 


Cursor_Wait 












































DeleteFont DeleteFont 
DeleteObject DeleteObject 
Disable Disable 
DisconnectKeyPress DisconnectKeyPress 
Display Display 

Draw Draw 
DrawAngleArc DrawAngleArc 
DrawArc DrawArc 
DrawLine DrawLine 
DrawPie DrawPie 
DrawPixel DrawPixel 
Enable Enable 
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Method... ..оп page 
FillDrawing FillDrawing 
FontColor FontColor 
FontToDC FontToDC 
ForegroundWindow ForegroundWindow 
FreeDC FreeDC 
GetArcDirection GetArcDirection 
GetClientRect GetClientRect 
GetDC GetDC 
getExStyleRaw getExStyleRaw 
GetFocus GetFocus 

GetID GetID 
GetMouseCapture GetMouseCapture 
GetPixel GetPixel 

GetPos GetPos 

GetRect GetRect 

GetSize GetSize 
getStyleRaw getStyleRaw 
getTextSize (deprecated) getTextSize (deprecated) 
getTextSizeScreen getTextSizeScrenn 
Group Group 





HasKeyPressConnection 


HasKeyPressConnection 





Hide 


Hide 
























































HideFast HideFast 

HScrollPos HScrollPos 
isEnabled isEnabled 
isMouseButtonDown isMouseButtonDown 
is Visible is Visible 
LoadBitmap LoadBitmap 
LogRect2AbsRect LogRect2AbsRect 
Move Move 

ObjectToDC ObjectToDC 
OpaqueText OpaqueText 
ProcessMessage ProcessMessage 
Rectangle Rectangle 

Redraw Redraw 
RedrawClient RedrawClient 
RedrawRect RedrawRect 
ReleaseMouseCapture ReleaseMouseCapture 
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Method... ..оп page 
RemoveBitmap RemoveBitmap 
Resize Resize 
RestoreCursorShape RestoreCursorShape 
ScreenToClient ScreenToClient 
Scroll Scroll 
SetArcDirection SetArcDirection 
SetColor SetColor 
SetCursorPos SetCursorPos 
SetFocus SetFocus 
SetFocusToWindow SetFocusToWindow 
SetFont setFont 
SetForegroundWindow SetForegroundWindow 
SetHScrollPos SetHScrollPos 
SetVScrollPos SetVScrollPos 
SetRect SetRect 

SetTitle SetTitle 

Show Show 

ShowFast ShowFast 
TabStop TabStop 
TabToNext TabToNext 
TabToPrevious TabToPrevious 
Title Title 

Title= Title= 
TransparentText TransparentText 
Update Update 

Value Value 

Value= Value= 
VScrollPos VScrollPos 
Write Write 
WriteToButton WriteToButton 
WriteToWindow WriteToWindow 





6.1. Appearance and Behavior Methods 


The following methods deal with the appearance or the behavior of the dialog control. The list contains 
methods to get or change the size, position, visibility, behavior, etc., of dialog controls. 


200 


ooRexx OODialog Reference Version 4.0.0 





Chapter 6. DialogControl Class 


6.1.1. Show 


2»-aDialogControl Shows sss sss ass sa Se ышы ын нынын == = >< 


The Show method makes a dialog control visible and activates it. 


Example: 
The following example makes the edit control NAME visible and activates it: 


MyDialog~GetEditControl ("NAME") ~Show 


6.1.2. Hide 


>>-aDialogControl Наде----------------------------< >< 


The Hide method makes a dialog or dialog control invisible and activates another dialog or dialog 
control. 


Example: 


MyDialog~GetEditControl ("МАМЕ") ~Hide 


6.1.3. HideFast 


2»-aDialogControl'HideFast-----------------cce socie eerie >< 


The HideFast method marks a dialog or dialog control as invisible but does not redraw it. Send the 
Update method (see page Update) to the dialog or dialog control to force a redraw. 


Example: 
MyDialog~GetEditControl ("NAME") ~HideFast 
MyDialog” Update 

6.1.4. ShowFast 


2»-aDiatogControl бнонЕаз------------------------- >< 


The ShowFast method marks a dialog or dialog control as visible but does not redraw it. Send the Update 
method (see page Update) to the dialog or dialog control to force a redraw. 


ooRexx OODialog Reference Version 4.0.0 201 


Chapter 6. DialogControl Class 


Example: 


MyDialog~GetEditControl ("NAME") ~ShowFast 


MyDialog~ Update 


6.1.5. Display 


+-NORMAL---+------ +--+ 

| +-FAST-+ | 
»»-aDialogControl^Display(--"--4-DEFAULT--4------4--4--"--)----»« 

| +-FAST-+ | 

+-HIDE----- 4------ +--+ 

| +-FAST-+ | 

*-INACTIVE----------- * 


The Display method displays (shows, makes visible, or invisible) a dialog control as specified. 


Argument: 


This argument can be one of the following keywords (case is not significant.) If no argument is 
given, the default keyword is NORMAL: 


NORMAL 
Shows (makes visible) the dialog control. Same as calling the Show method (see page Show). 


DEFAULT 


Default is an alias for NORMAL. The behavior is exactly the same for the two keywords. 


HIDE 


Hides (makes invisible) the dialog control. Same as calling the Hide method (see page Hide). 


INACTIVE 


Displays (shows, makes visible,) the dialog control in its current state. The active dialog 
remains active. When this method is invoked with the NORMAL keyword the dialog the control 
belongs to will be made the active window. If instead the INACTIVE keyword is used, the active 
window will not be changed. (Obviously, if the dialog that the control belongs to is already the 
active window, the INACTIVE keyword behaves exactly the same as the NORMAL keyword. 


To each keyword, except the INACTIVE keyword, you can add FAST, separated by a blank, to 
suppress the redrawing of the dialog control. 


Example: 
The following statement makes a tree control in the dialog visible without redrawing it. 


MyDialog^GetTreeControl(IDC TREECONTROL FILES)^Display ("NORMAL FAST") 
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This is usually done when there are a number of controls to make visible at one time. The 
programmer would make them all visible without redrawing. Then use the Update method to 
repaint everything at once. 


6.1.6. isVisible 
>2--1вуава ен ------------+--------+--+ >< 


Tests if the window (dialog or dialog control) is visible. 


Arguments: 


There are no arguments. 


Return value: 


Returns .true if the window is visible, otherwise .false 


Example: 


if \ self~isVisible then self~show 


6.1.7. Enable 


2»-aDiatogControl ЕнаБ?е----------<95н------- я pee eoo >< 


The Enable method enables a dialog or dialog control to accept user interaction. 


Example: 


MyDialog~GetEditControl ("Name") ~Enable 


6.1.8. Disable 


2»-aDiatogControl Пъвае---------------------<---<- >< 


The Disable method disables a dialog or dialog control. 


Example: 


MyDialog~GetEditControl ("Name") ~Disable 
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6.1.9. isEnabled 


22>=lsknabil ed=ss3sS S33 sSs5S5 SSS sah шыш ы SSeS ae SSS SS SSS SRS eee >< 


Tests if the window (dialog or dialog control) is enabled 


Arguments: 


There are no arguments. 


Return value: 


Returns .true if the window is enabled, otherwise .false 


Example: 


::method toggleState private 
listView = self~getListControl (IDC_LV_NAMES) 
if listView^isEnabled then 
listView^disable 
else 
listView^enable 


6.1.10. Group 


»»-aDialogControl^Group(--4----------- *--)--------------------- >< 
+-wantStyle-+ 


Add or remove the group style for this control. The group style controls how the user can navigate 
through the dialog using the keyboard. For most dialogs this does not change while the dialog is 
executing. However, in some dialogs the programmer may want to change the navigation depending on 
the options the user selects. 


Arguments: 


The only argument is 


wantStyle 


A boolean (.true or .false) to indicate whether the control should have or not have the group 
style. True (the default) indicates the control should have the group style and false indicates the 
control should not have the style. 


Return value: 


Negative values indicate the function failed, non-negative values indicate success. 
-4 or less 


The value is the negated Operating System Error code. The absolute value of the return can be 
used to look up the error reason in the Windows documentation. 
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-3 

The optional argument to the method is not a boolean. 
-2 

There is an (internal) problem with the dialog or the dialog handle. 
-1 

There is an (internal) problem with the resource ID of the control. 
О or greater 


The window style of the dialog control prior to adding or removing the group style. 


6.1.11. TabStop 


»»-aDialogControl^TabStop(--4----------- 4--)-------------------- >< 
+-wantStyle-+ 


Add or remove the tab stop style for the control. When a control has the tabstop style, the user can set the 
focus to the control by using the tab key. When a control does not have this style, the tab key will skip 
over the control. Adding or removing this style during the execution of a dialog allows the programmer 
to alter how the user navigates through the dialog controls. 


Arguments: 


The only argument is: 


wantStyle 


A boolean (.true or .false) to indicate whether the control should have or not have the tabstop 
style. True (the default) indicates the control should have the tabstop style and false indicates 
the control should not have the style. 


Return value: 


Negative values indicate the function failed, non-negative values indicate success. 


-4 or less 


The value is the negated Operating System Error code. The absolute value of the return can be 
used to look up the error reason in the Windows documentation. 


-3 
The second argument to the method is not a boolean. 


-2 


There is an (internal) problem with the dialog or the dialog handle. 
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-1 
There is an (internal) problem with the resource ID of the control. 


О or greater 


The window style of the dialog control prior to adding or removing the tabstop style. 


6.1.12. Resize 


»»-aDialogControl^Resize(--width--,--height--4----------------------------- +--)->< 
| +---------------- + | 
| ү | | 
+-,--"----+-HIDEWINDOW-+-+--"-+ 
+-SHOWWINDOW-+ 
+-NOREDRAW---+ 


The Resize method resizes a dialog or dialog control. 


Arguments: 


The arguments are: 
width 

The new width of the dialog or dialog control, in dialog units. 
height 

The new height of the dialog or dialog control, in dialog units. 


showOptions 


One or more of the following keywords, separated by blanks: 


HIDEWINDOW 


The dialog or dialog control is to be made invisible. 


SHOWWINDOW 


The dialog or dialog control is to be made visible. 


NOREDRAW 


The dialog or dialog control is to be repositioned without redrawing it. 
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Return value: 


0 
Resizing was successful. 
1 
Resizing failed. 
Example: 


The following example resizes the tree view control FILES almost to the size of the window and 
displays the new size: 


obj = MyDialog~GetTreeControl ("FILES") 

if obj = .Nil then return 

obj^Resize(MyDialog^SizeX -10, MyDialog^SizeY -20) 

parse value obj^GetSize with width height 

say "New width of window is" width "and new height is" height 


6.1.13. Move 


»»-aDialogControl^Move(--xPos--,--yPos--4---------------------------- +--)->< 
| +---------------- + | 
| ү | | 
+-,-"----+-HIDEWINDOW-+-+--"-+ 
+-SHOWWINDOW-+ 
+-NOREDRAW---+ 


The Move method moves the associated dialog or dialog control to the specified position. 


Arguments: 


The arguments are: 
xPos 
The new horizontal position of the dialog or dialog control, in dialog units. 


yPos 


The new vertical position of the dialog or dialog control, in dialog units. 


showOptions 


One or more of the following keywords, separated by blanks: 


HIDEWINDOW 


The dialog or dialog control is to be made invisible. 
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SHOWWINDOW 


The dialog or dialog control is to be made visible. 


NOREDRAW 


The dialog or dialog control is to be repositioned without redrawing it. 


Return value: 


0 
Moving was successful. 
1 
Moving failed. 
Example: 


The following example repositions the tree view control FILES to the upper left corner of the 
window and displays the new position: 


obj = MyDialog~GetTreeControl ("FILES") 

if obj = .Nil then return 

obj ~Move (1,1) 

parse value obj^GetPos with x y 

say "New horizontal position of window is" x "and new vertical position is" y 


6.1.14. SetForegroundWindow 


»»-aDialogControl^SetForegroundWindow(--hwnd--)--------------------------- >< 


The SetForegroundWindow method changes the foreground window to the window specified. The new 
window must be a top-level window or a dialog window. You can not make a dialog control window the 
foreground window. 


Arguments: 


The only argument is: 


hwnd 


The handle to the window that is to become the foreground window. 


Return value: 


The handle to the previous foreground window, or 0 if this method failed. 
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Example: 


This example makes another dialog the foreground window and returns the window handle of the 
current foreground window to the caller, or returns -1 if there was an error: 


::method switchToReportDlg 
expose reportDlg 
currentHwnd = self^setForeGroundwindow(reportDlg^dlgHandle) 
if currentHwnd == 0 then return -1 -- Report an error 
return currentHwnd 


6.1.15. ForegroundWindow 


»»-aDialogControl^ForegroundWindow----------------------------- >< 


The ForegroundWindow method returns the handle to the current foreground window. 


Return value: 


The handle to the foreground window, or 0 if this method failed. 


6.1.16. GetID 


22 -aDialogControl: GetID--------------------—-—-—---- шшш шун ы ыша: >< 


The GetID method retrieves the identification number of the associated dialog or dialog control. 


Return value: 


The numeric ID. 


Example: 
The following example displays 1 in most cases: 


say MyDialog^GetButtonControl("IDOK")^GetID 


6.1.17. getStyleRaw 


2»--gpetStyleRaw------------5--------uee-eoc-meenm >< 


The getStyleRaw method retrieves the window style flags of the dialog or dialog control. The flags аге 
returned in their numeric format. This allows the programmer to determine the current style of any dialog 
or control. However, the programmer needs to be able to look up the numeric value of the window style 
flags to make use of this functionality. This can be done using the Windows documentation and the 
Platform SDK. 
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Arguments: 


There are no arguments. 


Return value: 


The numeric value of the window style flags. 


Example: 


The following example gets the style flags for a tree control and then checks to see if drag and drop 
is enabled and if label editing is enabled. 


The value of the style flags has the potential of being larger than can be accommodated by the 
default numeric digits. Use numeric digits 11 if the returned value needs to be manipulated, for 
instance to use d2x on the value. 


Note: It is not necessary to convert the sty1e value in the example to its hexadecimal string 
representation before using it as an argument in the ana() method. That is just done in the 
example for display purposes. 


numeric digits 11 
TVS_DISABLEDRAGDROP = "0x0010" 
TVS. EDITLABELS "0x0008" 


treeControl = self^getTreeControl(IDC. TREE) 
style = treeControl^getStyleRaw 
style = "Ox" || style^d2x^right(8, 20?) 


if .DlgUtil^and( style, TVS DISABLEDRAGDROP ) <> 0 then stri = ’disabled’ 
else stri = ’enabled’ 


if .D1gUtil^and( Style, TVS EDITLABELS ) <> 0 then str2 = "enabled! 
else str2 = ’disabled’ 


say ’Tree-view Control styles’ 
say ? Raw style: > style 
say ’ Drag and drop:’ stri 
say ’ Edit labels: ^" str2 


/* Output could be: */ 
Tree-view Control styles 
Raw style: 0x5000002F 


Drag and drop: enabled 
Edit labels: enabled 
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6.1.18. getExStyleRaw 
>р--пеЦЕхбву!еКан-------------------------- >< 


The getExStyleRaw method retrieves Ше extended window style flags of the dialog or dialog control. 
The flags are returned in their numeric format. This function is very similar to the getStyleRaw() method, 
allowing the programmer to get the extended window flags. The numeric value of the extended style 
flags can be looked up using the Windows documentation and the Platform SDK. 


Arguments: 


There are no arguments. 


Return value: 


The numeric value of the window extended style flags. 


Example: 
The following example gets the extended style flags for a list-view control and displays them to the 
screen in hexadecimal format. The value displayed in the example indicates the following styles. 


WS EX NOPARENTNOTIFY == 0x00000004 
WS EX CLIENTEDGE == 0x00000200 


::method printExStyle private 
expose list 


val - list^getExStyleRaw 


numeric digits 11 

val = "Ox? || val^d2x^right(8, 0) 

say "List control extended style flag:" 
say " " val 

say 


/* Output could be: */ 


List control extended style flags: 
0x00000204 


6.1.19. GetRect 


»»-aDialogControl GethRect------------—---- cereum eet >< 


Retrieves the dimensions of the rectangle surrounding the associated dialog or dialog control. The 
coordinates are relative to the upper left corner of the screen and are specified in screen pixels. The order 
is: left, top, right, bottom; where ‘left’ and Тор" are the x and y coordinates of the upper left-hand corner 
of the rectangle, and 'right' and 'bottom' are the coordinates of the bottom right-hand corner. 
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Return value: 


The coordinates of the dialog or dialog control, separated by blanks. 


Example: 
The following example calculates the width and height of an entry line: 


parse value MyDialog^GetEditControl("Name")^GetRect with left top, 
right bottom 

width - right - left 

height = bottom - top 


6.1.20. SetRect 


»»-aDialogControl^SetRect(--x--,--y--,--width--,--height--» 
»-—----------------------------- *--)-------------------- >< 
| +---------------- + | 
| ү | | 
+-,--"'----+-NOMOVE-----+-4+--"-+ 
+-NOSIZE----- + 


+-HIDEWINDOW-+ 
+-SHOWWINDOW-+ 
+-NOREDRAW---+ 


The SetRect method sets new coordinates for the associated dialog or dialog control. 


Arguments: 


The arguments are: 
х,у 

The new position of the upper left corner, in screen pixels. 
width 

The new width of the dialog or dialog control, in screen pixels. 


height 


The new height of the dialog or dialog control, in screen pixels. 


showOptions 
One or more of the following keywords, separated by blanks: 
NOMOVE 


The upper left position of the dialog or dialog control is not changed. 


NOSIZE 


The size of the dialog or dialog control is not changed. 
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HIDEWINDOW 


The dialog or dialog control is to be made invisible. 


SHOWWINDOW 


The dialog or dialog control is to be made visible. 


NOREDRAW 


The dialog or dialog control is to be repositioned without redrawing it. 


Return value: 


Repositioning was successful. 


Repositioning failed. 


6.1.21. GetClientRect 


>>-aDialogControl~GetClientRect (--+------ *--)------------------ >< 


The GetClientRect method returns the client rectangle of a dialog or dialog control in screen pixels. The 
client coordinates specify the upper left and lower right corners of the client area. Because the client 
coordinates are relative to the upper left corner of the client area of a dialog or dialog control, the 
coordinates of the upper left corner are (0,0). 


Arguments: 


The only argument is: 


hwnd 


The handle to a dialog or dialog control. If this argument is omitted, the dimensions of the 
associated dialog or dialog control are returned. 


Return value: 


The client rectangle in the format "left top right bottom", separated by blanks. 
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6.1.22. GetSize 


22-aDiatogControl"GetSize---------—---—----cm aS SSS Sessa Sasa eec >< 


The GetSize method returns the width and height of the dialog or dialog control, in dialog units. 


Return value: 


The width and height, separated by a blank. 


Example: 


For an example, see Resize. 


6.1.23. AssignFocus 


2»-aDialogControl'AssignPocus-------------------5--4c----2--oc >< 


The AssignFocus method sets the input focus to the associated dialog control. 


6.1.24. GetFocus 


>>-aDialogControl” СеъЕосив-----------------------------<- >< 


The GetFocus method returns the handle to the dialog control that currently has the input focus. 


Return value: 


The handle to the dialog control that has the input focus, or 0 if this method failed. 


6.1.25. SetFocus 


»»-aDialogControl^SetFocus(--hwnd--)--------------------------- >< 


The SetFocus method sets the input focus to a dialog control and returns the handle of the control that 
previously had the focus. 


Arguments: 


The only argument is: 


hwnd 


The handle to the dialog control that is to receive the input focus. 
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Return value: 


-1 

The method failed. 
0 

The focus was changed, but the control with the previous focus could not be determined. 
Other 


The handle to the control with the previous focus. 


6.1.26. SetFocusToWindow 


»»-aDialogControl^SetFocusToWindow(--hwnd--)------------------- >< 


The SetFocusToWindow method moves the input focus to another top-level window or dialog. This has 
the effect of bringing that window to the foreground. This method returns a handle to the dialog control 
that previously had the input focus. 


Arguments: 


The only argument is: 


hwnd 


The handle to the top-level window or dialog that is to receive the input focus. 


Return value: 


-1 

The method failed. 
0 

The focus was changed, but the control with the previous focus could not be determined. 
Other 


The handle to the control with the previous focus. 
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6.1.27. SetColor 


»»-aDialogControl^SetColor(--background--,--foreground--)------ >< 


The SetColor method sets the background and foreground colors of the dialog control. 


Arguments: 


The arguments are: 


background 
The color number of the background color. 
foreground 


The color number of the foreground color. 


Return value: 


0 
The color has been assigned. 
1 
The selected color was already assigned. 
Example: 


The following example sets the background color of list box FILES to blue: 


MyDialog^GetListBox("FILES")^SetColor(4, 15) 


6.1.28. Update 


»»-aDialogControl" Update----------------2--------5-----995--72-7--- >< 


The Update method makes the contents of the dialog or dialog control invalid and therefore forces it to 
be updated. 


6.1.29. Title 


22-aDialogControl Titles sess se sss tes Tasers >< 


The Title method retrieves the title of the dialog or dialog control. 
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Return value: 


The title was retrieved. 


Retrieving the title failed. 


6.1.30. Title= 
»»-aDialogControl^Title---new title---------------------------- >< 
The Title= method sets the title of the dialog or dialog control. 


Arguments: 


The only argument is: 


new_text 


A text string that is to be used as the title or text of the dialog or dialog control. 


Return value: 


0 
The title was set. 
1 
Setting the title failed. 
Example: 


The following example changes the label of radio button CHOICE2: 


MyDialog^GetRadioControl("CHOICE2")^Title-"&Übject Rexx (preferred choice)" 
MyDialog”~ Redraw 


6.1.31. SetTitle 


»»-aDialogControl^SetTitle(--new title--)---------------------- >< 


The SetTitle method sets the title of the dialog or dialog control. It is equal to Title=. 
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6.2. Miscellaneous Dialog Control Methods 


The following methods are general purpose dialog control methods. 


6.2.1. ProcessMessage 


»»-aDialogControl^ProcessMessage(--message--,--firstParam--,--secondParam--)-»5« 


The ProcessMessage method sends a Windows message to a dialog control. 


Arguments: 


The arguments are: 


message 


The number of the message to be sent to the dialog control. 


firstParam,secondParam 


Additional arguments specific to the message. 


Return value: 


The return values are message-specific. 


Example: 


The following example erases the background of the edit control with the resource ID (symbolic ID) 
of IDC EDITI: 


dlgc = MyDialog^GetEditControl("IDC EDIT1") 

WM ERASEBACKGROUND = "14"~x2d 

hdc = dlgc^GetDc 

dlgc^ProcessMessage(WM ERASEBACKGROUND, hdc, 0) 
dlgc^FreeDC(hdc) 


Note: Use the Windows documentation and Platform SDK to obtain the Window message numbers. 


6.2.2. Value 


2»-aDiatogÜontrol Мапше-------------------------<< >< 


The Value method retrieves the current value of a dialog control. 
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Return value: 


The current value set in the dialog control. 


Note: See GetValue for more information. 


6.2.3. Value= 


»»-aDialogControl^Value---nevw value---------------------------- >< 


The Value= method sets a value for a dialog control. 


Arguments: 


The only argument is: 


new_value 


The value assigned to the dialog control. 


Example: 
The following example selects check box RESTART and deselects check box VERIFY: 


MyDialog~GetCheckControl ("RESTART") ~Value=1 
MyDialog~GetCheckControl ("VERIFY") ~Value=0 


Note: See SetValue for more information. 


6.3. Connect Event Methods 


The following methods connect dialog control events to methods the programmer defines in the parent 
dialog class. 


6.3.1. ConnectKeyPress 


>>-aDialogControl~ConnectKeyPress (--шзрТоВа1зе--,--Кеув--+----------- +--)---->< 
+-,-filter--+ 


The ConnectKeyPress method connects a key down event, when the control has the keyboard focus, with 
a programmer defined method in the parent dialog of the control. The underlying Windows dialog must 
exist before this method can be invoked. 
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Note: This method is only available on systems running Windows ХР or later. On earlier versions of 
Windows, the method will fail and return -4. 


The arguments, return values, and behavior of this method are the same as those for the 
ConnectKeyPress method of the BaseDialog. However, the method of the BaseDialog connects any key 
down event when the dialog is the active window and this method of the DialogControl only connects 
the key down events when the specific control has the focus. See the ConnectKeyPress method of the 
BaseDialog for a detailed description of the arguments, return values, and behavior. 


Arguments: 


The arguments are: 


msgToRaise 
The method to be invoked for the key down event. 
keys 


The key, or list of keys, whose key down event will invoke the method specified by 


msgToRaise. 


filter 


An optional filter to be applied to the key down event. 


Return value: 


The return values are: 


0 

Success. 
1 

The underlying mechanism in the Windows API failed. 
-1 

A problem with one of the arguments. 
-2 

An (internal) problem with the dialog window. 
-3 

An (internal) problem with the dialog administration. 
-4 


This method is not supported by this version of Windows. Windows XP or later is required. 


220 ooRexx OODialog Reference Version 4.0.0 


Chapter 6. DialogControl Class 


-5 
Memory allocation error in the underlying Windows API. 
-6 
The maximum number of connections has been reached. 
-7 
The msgToRaise method is already connected to a key down event for this dialog control. 
Event Method Arguments 


The ooDialog method connected to the key press event will receive the following five arguments in 
the order listed: 


keyCode 


The numeric code of the key pressed. 


shift 


True if a shift key was down at the time of the event and false if the shift key was not down. 


control 


True if a control key was down at the time of the key press, false if it was not. 


alt 


True if an alt key was down at the time of the key press, false if it was not. 


extraInfo 


This argument is a string containing keywords. It supplies extra information about the 
keyboard state at the time of a key press event. The string will contain some combination of 
these keywords 


numOn 


Num Lock was on at the time of the key press event. 


numOff 


Num Lock was off. 


capsOn 


Caps Lock was on at the time of the key press event. 


capsOff 
Caps Lock was off. 


scrollOn 


Scroll Lock was on at the time of the key press event. 
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scrollOff 
Scroll Lock was off. 


IShift 


The left shift key was down at the time of the key press event. 


rShift 
The right shift key was down. 


IControl 


The left control key was down at the time of the key press event. 


rControl 


The right control key was down. 


1Alt 


The left alt key was down at the time of the key press event. 


rAlt 
The right alt key was down. 


Example: 


The following example could be from an application that supplies extended editing abilities for a 
multi-line edit control. When the edit control has the focus the user can use Alt-D to delete the 
current word, Ctrl-D to delete the current line, and Shift-Alt-D delete the current paragraph: 


::method initDialog 
expose editControl 


editControl = self^getEditControl(IDC EDTIT) 


-- Capture the D key press when either the Alt or Control keys are 
-- also pressed. 
editControl~connectKeyPress(onDPress, self~vCode(’D’), "ALT CONTROL") 


::method onDPress 
expose editControl 
use arg key, shift, control, alt, info 


-- Determine which of the key press combinations this is and take 
-- appropriate action if it is a combination we are interested in. 


isAltD = \ shift & \ control & alt 


isCtrlD = \ shift & control & \ alt 
isShiftAltD = shift & \ control & alt 
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if isAltD then self^deleteWord(editControl) 
if isCtrlD the self^deleteLine(editControl) 
if isShiftAltD then self~deleteParagraph(editControl) 


6.3.2. ConnectFKeyPress 


»»-aDialogControl^ConnectFKeyPress(--msgToRaise--)------------- >< 


The ConnectFKeyPress method is a convenience method that connects all Е key down events, when the 
control has the keyboard focus, with a programmer defined method in the parent dialog of the control. 
(This is for the standard function keys, F2 through F24.) The underlying Windows dialog must exist 
before this method can be invoked. 


Note: This method is only available on systems running Windows XP or later. On earlier versions of 
Windows, the method will fail and return -4. 


The arguments, return values, and behavior of this method are the same as those for the 
ConnectFKeyPress method of the BaseDialog. However, the method of the BaseDialog class connects 
any F key down event when the dialog is the active window and this method of the DialogControl class 
only connects the F key down events when the specific control has the focus. See the ConnectFKeyPress 
method of the BaseDialog for a more detailed description of the arguments, return values, and behavior. 


Arguments: 


The required argument is: 


msgToRaise 


The method to be invoked for the key down event. 


Return value: 


The return values are: 


0 
Success. 
1 
The underlying mechanism in the Windows API failed. 
-1 
A problem with one of the arguments. 
-2 


An (internal) problem with the dialog window. 
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-3 
An (internal) problem with the dialog administration. 
-4 
This method is not supported by this version of Windows. Windows XP or later is required. 
-5 
Memory allocation error in the underlying Windows API. 
-6 
The maximum number of connections has been reached. 
-7 
The msgToRaise method is already connected to a key down event for this dialog control. 
Event Method Arguments 


The ooDialog method connected to the F key down event receives five arguments. This arguments 
are described in detail in the ConnectKeyPress method of the DialogControl. 


Example: 


The following example connects the F key down events for an edit control. The application 
determines which F key was pressed and takes appropriate action. For this application, the F3 key is 
the search key. 


::method initDialog 
expose editControl searchToken 


editControl = self^getEditControl(IDC EDIT) 
editControl^connectFKeyPress(onFKey) 


lastSearchToken = "" 
::method onFKey 


expose editControl searchToken 
use arg key 


select 
when self^keyName(key) == ?Е2? then do 
end 
when self^keyName(key) == ’F3’ then do 
description - "What word would you like to search for?" 


searchToken = inputBox(description, "Search", searchToken) 


if searchToken <> "" then 
self^findAndHighlight(searchToken, editControl) 
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end 
when self^keyName(key) == ’F4’ then do 


end 


end 


6.3.3. DisconnectKeyPress 


»»-aDialogControl^DisconnectKeyPress(--4-------------- +--)----- >< 
+--methodName--+ 


The DisconnectKeyPress method disconnects a previously connected method with a key down event. If 
no method name is specified than all key down event connections are removed. Otherwise, only the key 
down events connected to the specific method are removed. 


Note: This method is only available on systems running Windows XP or later. On earlier versions of 
Windows, the method will fail and return -4. 


The arguments, return values, and behavior of this method are the same as those for the 
DisonnectKeyPress method of the BaseDialog. However, this method only works for connections made 
using the DialogControl's ConnectKeyPress method. It can not work with a connection made though 
the BaseDialog’s method. See the DisconnectKeyPress method of the BaseDialog for a more detailed 
description of the behavior of this method. 


Arguments: 


The single optional argument is: 


methodName 


If methodName is specified, only the key down events connected to that method are 
disconnected. If the argument is omitted, then all key down events for the dialog control will be 
disconnected. 


Return value: 


The return values are: 


Success. 


The underlying mechanism in the Windows API that captures the key down events failed to 
disconnect. 
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-1 
The specified methodName is not connected to any key down events for this control. 
-2 
The underlying mechanism in the Windows API that captures the key down events was never 
installed. 
-4 
This method is not supported by this version of Windows. Windows XP or later is required. 
Example: 


The following example could come from a dialog where the user can enable or disable the user of 
hot keys when she is working within an edit control. When the user presses the disable hot keys 
button, the dialog disables the hot keys for the edit control by removing the key press connections. 


::method defineDialog 
self~addButton(IDC_PB_DISABLE, 60, 135, 65, 15, "Disable Hot Keys", onDisable) 


method onDisable 
editControl = self^getEditControl(IDC, EDIT) 
editControl^disconnectKeyPress 


6.3.4. HasKeyPressConnection 


»»-aDialogControl^HasKeyPressConnection(--4-------------- *--)----- >< 
+--methodName--+ 


This method is used to query if a connection to a key down event already exists. 


Note: This method is only available on systems running Windows ХР or later. On earlier versions of 
Windows, the method will fail and return -4. 


The arguments, return values, and behavior of this method are the same as those for the 
HasKeyPressConnection method of the BaseDialog. However, this method only works for connections 
made using the DialogControl’s ConnectKeyPress method. It can not work with a connection made 
though the BaseDialog’s method. The HasKeyPressConnection method of the BaseDialog may provide 
some additional insight into the behavior of this method. 
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Arguments: 


The single optional argument is: 


methodName 


When this argument is not used, HasKeyPressConnection queries if any key down event for the 
dialog control is connected to a method. When methodName is specified, the query checks for a 
connection to the specified method. 


Return value: 


The returned value is always true or false. 
true 

A connection exists. 
false 


No connection exists. 


Example: 


The following example is from an application where the user can enable the use of hot keys when 
an edit control has the focus, or not. The reset push button is used in the application to reset the state 
of the dialog. One of the things done when the state is reset to check or uncheck a check box that 
shows whether hot keys are currently enabled or not. 


::method defineDialog 


self^addCheckBox(IDC CHECK FKEYSENABIED, , 30, 60, , , "Hot Keys Enabled") 


self^addButton(IDC PB RESET, 60, 135, 45, 15, "Reset", onReset) 
::method onReset 


editControl = self^getEditControl(IDC, EDIT) 
if editControl~hasKeyPressConnection then 
self^getCheckControl(IDC, CHECK, FKEYSENABIED) ~check 


else 
self^getCheckControl(IDC, CHECK, FKEYSENABIED)^uncheck 


6.4. Draw Methods 


The following methods are used to draw, redraw, and clear a dialog or dialog control. 
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6.4.1. Draw 


22»-caDzatogControl Draw ssa SSRs Ss sS ra Sasa езш чы a See >< 


The Draw method draws the dialog or dialog control. 


Return value: 


Drawing was successful. 


Drawing failed. 


6.4.2. Clear 


>> saDialogControl® СТ1ван---<--<----# те тт see Se rast >< 


The Clear method draws the dialog or dialog control using the background brush. 


Return value: 


Clearing was successful. 


Clearing failed. 


6.4.3. ClearRect 


>>-aDialogControl~ClearRect (--left-- ,--top-- ,--right-- ,--bottom--)->< 


The ClearRect method draws the dialog or dialog control using the background brush. 
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Arguments: 


The arguments are: 


left,top 


The upper left corner of the rectangle, in screen pixels. 


right,bottom 


The lower right corner of the rectangle, in screen pixels. 


Return value: 


Drawing was successful. 


Drawing failed. 


6.4.4. Redraw 


»»-aDialogControl'Redràw-------------------2----2------9---2--2-- >< 


The Redraw method redraws the dialog or dialog control immediately. 


Return value: 


Redrawing was successful. 


Redrawing failed. 


6.4.5. RedrawRect 
»»-aDialogControl^RedrawRect (--left--,--top--,--right--,--bottom--» 


>--+----------- 4--)---------------------------------------------- >< 


+-,erasebkg-+ 
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The RedrawRect method immediately redraws the rectangle of the client area of the associated dialog. 
You can specify whether the background of the dialog is to be erased before redrawing. 


Arguments: 


The arguments are: 


left,top 


The upper left corner of the rectangle relative to the client area, in screen pixels. 


right,bottom 


The lower right corner of the rectangle relative to the client area, in screen pixels. 


erasebkg 


If this argument is | or "Y", the background of the dialog is erased before repainting. 


Return value: 


Redrawing was successful. 


Redrawing failed. 


6.4.6. RedrawClient 


»»-aDialogControl^RedrawClient (--erasebkg--)------------------- >< 


The RedrawClient method immediately redraws the entire client area of the dialog or dialog control. You 
can specify whether the background of the dialog or dialog control is to be erased before redrawing. 


Arguments: 


The only argument is: 


erasebkg 


If you specify 1 or "Y", the background of the dialog is erased before redrawing. 
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Return value: 


Redrawing was successful. 


Redrawing failed. 


6.5. Conversion Methods 


The following methods are used to convert and map coordinates of a dialog or dialog control. 


6.5.1. LogRect2AbsRect 


>>-aDialogControl~ LogRect2AbsRect (--left--,--top--,--right--,--bottom--)-»« 


The LogRect2AbsRect method converts the coordinates from dialog units to screen pixels. 


Arguments: 


The arguments are: 


left,top 


The position of the upper left corner, in dialog units. 


right,bottom 


The position of the lower right corner, in dialog units. 


Return value: 


A compound variable that stores the four screen pixel coordinates. The position of the upper left 
corner is stored in RetStem.left and RetStem.top. The position of the lower right corner is stored in 
RetStem.right and RetStem.bottom. The tails left, top, right, and bottom must be uninitialized 
symbols. 


Example: 


absrect. = MyDialog~LogRect2AbsRect(5, 5, 10, 10) 
say "Screen pixel rectangle=" absrect.left "," absrect.top ",", 
absrect.right "," absrect.bottom 
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6.5.2. AbsRect2LogRect 


>>-aDialogControl~ AbsRect2LogRect (--left-- ,--top-- ,--right-- ,--bottom-—)->< 


The AbsRect2LogRect method converts the coordinates from screen pixels to dialog units. 


Arguments: 


The arguments are: 
left,top 

The position of the upper left corner, in screen pixels. 
right,bottom 


The position of the lower right corner, in screen pixels. 


Return value: 


A compound variable that stores the four screen dialog units. The position of the upper left corner is 
stored in RetStem.left and RetStem.top. The position of the lower right corner is stored in 
RetStem.right and RetStem.bottom. The tails left, top, right, and bottom must be uninitialized 
symbols. 


Example: 


rectdunit. = MyDialog^AbsRect2LogRect(20, 20, 40, 40) 
say "Dialog unit rectangle-" rectdunit.left "," rectdunit.top ",", 
rectdunit.right "," rectdunit.bottom 


6.5.3. ScreenToClient 


»»-aDialogControl^ScreenToClient(--x--,y--)-------------------- >< 


The ScreenToClient method maps the coordinates relative to the upper left corner of the screen, to a 
location within the client area relative to the upper left corner of the dialog’s client area. 


Arguments: 


The arguments are: 


The horizontal position, in screen pixels. 


The vertical position, in screen pixels. 
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Return value: 


The horizontal and vertical positions of the specified location relative to the upper left corner of the 
client area, separated by a blank. 


6.5.4. ClientToScreen 


»»-aDialogControl^ClientToScreen(--x--,y--)-------------------- >< 


The ClientToScreen method maps the coordinates relative to the dialog’s client area to the coordinates 
relative to the upper left corner of the screen. 


Arguments: 


The arguments are: 


The horizontal position in screen pixels. 


The vertical position in screen pixels. 


Return value: 


The horizontal and vertical positions of the specified location relative to the location (0,0) of the 
screen, separated by a blank. 


6.6. Scroll Methods 


The following methods are used to scroll a dialog or dialog control and to set scroll bars. 


6.6.1. Scroll 


»»-aDialogControl^Scroll(--cx--,--cy--)------------------------ >< 


The Scroll method scrolls the contents of the associated dialog or dialog control by the amount specified. 
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Arguments: 


The arguments are: 


CX 


The number of screen pixels the content of the dialog or dialog control is to be scrolled to the 
right or to the left, if negative. 


cy 
The number of screen pixels the content of the dialog or dialog control is to be scrolled 


downward or upward, if negative. 


Return value: 


Scrolling was successful. 


Scrolling failed. 


6.6.2. HScrollPos 


»»-aDialogControl*HScrollPos---------------------------29-7------ >< 


The HScrollPos method returns the position of the horizontal scroll bar in the associated dialog or dialog 
control. 


Return value: 


The position of the horizontal scroll bar. 


6.6.3. VScrollPos 


>>-aDialogControl” VScrollP0os------------------2------e-2---7---7 >< 


The VScrollPos method returns the position of the vertical scroll bar in the associated dialog or dialog 
control. 


Return value: 


The position of the vertical scroll bar. 
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6.6.4. SetHScrollPos 


+-1------ + 
>>-aDialogControl~SetHScrollPos(--position-- ,--+-------- +--)--->< 
+-redraw-+ 


The SetHScrollPos method sets the thumb position of the horizontal scroll bar contained in the 
associated dialog or dialog control. 


Arguments: 


The arguments are: 
position 

The new thumb position of the horizontal scroll bar. 
redraw 


If this argument is | (the default), the display of the scroll bar is updated. 


Return value: 


The previous position of the horizontal scroll bar, or 0 if this method failed. 


6.6.5. SetVScrollPos 


+-1------ + 
>>-aDialogControl~SetVScrollPos(--position-- ,--+-------- +--)--->< 
+-redraw-+ 


The SetVScrollPos method sets the thumb position of the vertical scroll bar contained in the associated 
dialog or dialog control. 


Arguments: 


The arguments are: 


position 
The new thumb position of the vertical scroll bar. 
redraw 


If this argument is | (the default), the display of the scroll bar is updated. 


Return value: 


The previous position of the vertical scroll bar, or 0 if this method failed. 
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6.7. Mouse and Cursor Methods 


The following methods are used to position and shape the mouse cursor and to capture the mouse. 


6.7.1. CursorPos 
»»-aDiatogÜControl СитвогРов--------------------<- >< 
The CursorPos method returns the current position of the mouse cursor. 


Return value: 


The horizontal and vertical position of the mouse, separated by a blank. 


Example: 


See SetCursorPos for an example on how to use this method. 


6.7.2. SetCursorPos 


»»-aDialogControl^SetCursorPos(--x--,y--)---------------------- >< 


The SetCursorPos method moves the mouse cursor to the specified position. This method can be used to 
force the repainting of the mouse cursor or to keep the mouse cursor within a specific rectangle. 


Arguments: 


The arguments are: 


The horizontal position of the mouse cursor, in screen pixels. 


The vertical position of the mouse cursor, in screen pixels. 


Return value: 


Moving the mouse cursor was successful. 


Moving the mouse cursor failed. 
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Example: 


The following example shows two methods: one indicating that processing has started and one 
indicating that processing has completed. The method IndicateBeginProcessing changes the shape 
of the mouse cursor to the WAIT cursor and IndicateEndProcessing restores the original mouse 
cursor shape. Both methods retrieve the current position of the mouse cursor and move it by one 
screen pixel in each direction to force the repainting of the mouse cursor. 


::method IndicateBeginProcessing 
self^Current Cursor = self^Cursor Wait 
parse value self^CursorPos with curx cury 
self~SetCursorPos(curx+1, сигу+1) 


::method IndicateEndProcessing 
self^RestoreCursorShape(self^Current Cursor) 
parse value self^CursorPos with curx cury 
self^SetCursorPos(curx-1, cury-1) 


See DefListDragHandler for another example on how to use the mouse methods. 


6.7.3. RestoreCursorShape 


»»-aDialogControl^RestoreCursorShape(--4-------------- +--)----- >< 
+-CursorHandle-+ 


The RestoreCursorShape method restores the shape of the mouse cursor. 


Arguments: 


The only argument is: 


CursorHandle 


The handle to the mouse cursor shape returned by the Cursor_Arrow, Cursor_AppStarting, 
Cursor_Cross, Cursor_No, or Cursor_Wait method. 


If you omit this argument, the cursor shape is set to an arrow. Therefore, it is recommended that 
you store the original mouse cursor shape by specifying its handle when you change its shape. 


Return value: 


The handle to the current cursor shape, that is, the shape that was used before the cursor was 
restored to the given shape. 


Example: 


See SetCursorPos for an example on how to use this method. 
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6.7.4. Cursor_Arrow 


»»-aDialogControl^Cursor Arrow--------------------------------- >< 


The Cursor_Arrow method sets the shape of the mouse cursor to the standard arrow. The new shape is 
only used when the mouse cursor is within the rectangle of the associated dialog or dialog control. 


Return value: 


The handle to the current cursor shape, that is, the shape that was used before the arrow shape was 
set. 


Example: 


See SetCursorPos for an example on how to use this method. 


6.7.5. Cursor_AppStarting 


»»-aDialogControl^Cursor AppStarting--------------------------- >< 


The Cursor_AppStarting method sets the shape of the mouse cursor to the standard arrow with a small 
hourglass. The new shape is only used when the mouse cursor is within the rectangle of the associated 
dialog or dialog control. 


Return value: 


The handle to the current cursor shape, that is, the shape that was used before the arrow shape with 
the hourglass was set. 


Example: 


See SetCursorPos for an example on how to use this method. 


6.7.6. Cursor Cross 


»»-aDialogControl^Cursor Cross--------------------------------- >< 


The Cursor_Cross method sets the shape of the mouse cursor to a crosshair. The new shape is only used 
when the mouse cursor is within the rectangle of the associated dialog or dialog control. 


Return value: 


The handle to the current shape, that is, the shape that was used before the crosshair cursor shape 
was set. 
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Example: 


See SetCursorPos for an example on how to use this method. 


6.7.7. Cursor No 


2»-aDiatogControl Cursor Но--------------------<+--- ----- >< 


The Cursor_No method sets the shape of the mouse cursor to a slashed circle to deny access. The new 
shape is only used when the mouse cursor is within the rectangle of the associated dialog or dialog 
control. 


Return value: 


The handle to the current shape, that is, the shape that was used before the slashed-circle cursor 
shape was set. 


Example: 


See SetCursorPos for an example on how to use this method. 


6.7.8. Cursor Wait 


2»-aDiatogControl Cursor На ------------------------- >< 


The Cursor_Wait method sets the shape of the mouse cursor to the hourglass. The new shape is only used 
when the mouse cursor is within the rectangle of the associated dialog or dialog control. 


Return value: 


The handle to the current shape, that is, the shape that was used before the hourglass shape was set. 


Example: 


See SetCursorPos for an example on how to use this method. 


6.7.9. GetMouseCapture 


»»-aDialogControl^GetMouseCapture------------------------------ >< 


The GetMouseCapture method retrieves the dialog or dialog control that captured the mouse. This dialog 
or dialog control receives the entire mouse input regardless of whether the mouse cursor is within the 
borders of the dialog or dialog control. 
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Return value: 


The handle to the dialog or dialog control that captures the mouse, or 0 if the mouse is not captured. 


6.7.10. CaptureMouse 


»»-aDialogControl^CaptureMouse--------------------------------- >< 


The CaptureMouse method captures the mouse. This means that the associated dialog or dialog control 
receives the entire mouse input regardless of whether the mouse cursor is within the borders of the dialog 
or dialog control. 


Return value: 


The handle to the dialog or dialog control that previously captured the mouse, or 0 if the mouse was 
not captured before. 


Note: If you change the cursor shape while the mouse is being captured, this change is ignored. 


6.7.11. ReleaseMouseCapture 


»»-aDialogControl^ReleaseMouseCapture-------------------------- >< 


The ReleaseMouseCapture method releases the mouse capture from a dialog or dialog control and 
restores normal mouse input processing. This means that the mouse input is then received by another 
dialog or dialog control that captured the mouse. 


Return value: 


The mouse capture was released. 


Releasing the mouse capture failed. 


6.7.12. IsMouseButtonDown 


»»-aDialogControl^IsMouseButtonDown(--"--4-LEFT---4--"--)------ >< 
+-MIDDLE-+ 
+-RIGHT--+ 
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The IsMouseButtonDown method retrieves information on whether a mouse button is pressed. 


Arguments: 


The only argument is: 


button 


The location of the mouse button you are interested in. 


Return value: 


The button is not being pressed. 


The button is being pressed. 


6.8. Bitmap Methods 


The following methods load and release bitmaps. 


6.8.1. LoadBitmap 


»»-aDialogControl^LoadBitmap(--bmpFilename--4------------- +--)->< 
+-,--"USEPAL"-+ 


The LoadBitmap method loads a bitmap from a file into memory and returns the handle to the bitmap. 


Arguments: 


The arguments are: 


bmpFilename 


The name of a bitmap file. The name can also include a relative or absolute path. 


USEPAL 


Sets the color palette of the bitmap as the system color palette. 
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Example: 


The following example loads into memory the bitmap file, Walker . bmp, which is located in the BMP 
subdirectory. hBmp is the handle to this in-memory bitmap. 


hBmp = MyDialog~LoadBitmap("bmp\Walker. bmp", "USEPAL") 


Note: Do not forget to call the RemoveBitmap method to free memory when the bitmap is no longer 
in use. You have to specify the INMEMORY option when using the ConnectBitmapButton or 
ChangeBitmapButton method. 


6.8.2. RemoveBitmap 


»»-aDialogControl^RemoveBitmap(--hBitmap--)-------------------- >< 


The RemoveBitmap method frees an in-memory bitmap that was loaded by LoadBitmap. 


Arguments: 


The only argument is: 


hBitmap 
The bitmap handle. 


6.9. Device Context Methods 


The following methods are used to retrieve and release a device context (DC). 


A device context (DC) is associated with a dialog or dialog control, and is a drawing area managed by a 
dialog or dialog control. It stores information about graphic objects (such as bitmaps, lines, and pixels 
that are displayed) and the tools (such as pens, brushes, and fonts) that are used to display them. 


6.9.1. GetDC 


>2-ablalogControl Get DO =ssas S$ ssh sss SSS SSS SSS a SS SSS Seas >< 


The GetDC method reserves drawing resources and returns the handle to the display device context of a 
dialog or dialog control. 


Return value: 


The handle to the device context, or 0 if this method failed. 
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Example: 


The following example retrieves the device context of button DRAWINGS, processes the drawing 
commands, and frees the device context resources: 


obj = MyDialog~GetButtonControl ("DRAWINGS") 
if obj = .Nil then return -1 
dc = obj^GetDC 
if dc - O then return -1 
. /* draw something */ 
obj^FreeDC(dc) 


Note: When you have finished with the device context, call FreeDC. 


6.9.2. FreeDC 


»»-aDialogControl^FreeDC(--dc--)------------------------------- >< 


The FreeDC method releases the device context resources that were reserved for GetDC. 


Arguments: 


The only argument is: 


dc 


The handle to the device context that is to be released. 


Return value: 


0 

The device context resources were released. 
1 

Releasing the device context resources failed. 
Example: 


See GetDC for an example. 


Note: Always call this method when you have finished with the device context. 
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6.10. Text Methods 


The following methods are used to display text dynamically in a window area and to modify the state of 
a device context. See GetWindowDC, GetDC, and GetButtonDC for information on how to retrieve a 
device context. 


6.10.1. Write 


»»-aDialogControl^Write(--xPos--,--yPos--,--text---------------- ? 
B-—4-------------------------------------- 4--------------------- > 
| +-"5Ү5ТЕМ"-+ | 
+-,--+---------- +--+----------------- +-+ 
+-fontName-+ | *-10------- + | 
+-,--+---------- +-+ 


»-—-------------------------------------------------------------------------- +--)->< 
+-+---------------------------------------------------------------------- +-+ 
+-+------------------------------------------------------------------ +-+ 

| +----------------- + | 

| V +-OPAQUE------ + | | 

+-,--"----+-THIN-------- +-+--"--+-------------------------------- +-+ 
+-EXTRALIGHT--+ +-,--+--------- +--+------------ +-+ 
*T-LIGHI------- * *-fgColor-* +-,--bkColor-+ 
*-MEDIUM------ * 


+-SEMIBOLD----+ 
+-EXTRABOLD---+ 


*-BOLD-------- * 
*-HEAVY------- * 
+-UNDERLINE---+ 
*-ITALIC------ * 


+-STRIKEQUT---+ 
+-TRANSPARENT-+ 
*-CLIENT------ * 


The Write method writes the specified text to the device context associated with the dialog or dialog 
control in the given font, style, and color at the given position. 


Arguments: 


The arguments are: 


xPos, yPos 


The starting position of the text, in pixels. 


text 


The string that you want to write to the dialog or dialog control. 
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fontName 


The name of a font. If omitted, the SYSTEM font is used. 


fontSize 


The size of the font. If omitted, the standard size (10) is used. 


fontStyle 


One or more of the keywords listed in the syntax diagram, separated by blanks: 


TRANSPARENT 


This style writes the text without clearing the background. 


OPAQUE 


This style, which is the default, clears the background with the given background color, or 
with white if the background color is omitted, before writing the text. 


CLIENT 


The device context of the client area of the dialog or dialog control is used instead of the 
device context of the entire dialog or dialog control. 


fgcolor 


The color index of the text color. 


bkColor 


The color index of the background color. The background color is not used in transparent 
mode. 


Example: 


The following example writes the string "Hello world!" to the dialog using a blue 24pt Arial font in 
bold and transparent, italic style: 


MyDialog^Write(5, 5, "Hello world!", "Arial", 24, , 
"BOLD ITALIC TRANSPARENT CLIENT", 4) 


6.10.2. WriteDirect 


»»-aDialogControl^WriteDirect (--dc--,--xPos--,--yPos--,--text--)-»« 


The WriteDirect method enables you to write text to a device context at a given position. 
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Arguments: 
The arguments are: 
dc 
A device context. 


xPos, yPos 


The position where the text is placed, in pixels. 


text 


The string you want to write to the dialog or dialog control. 


6.10.3. TransparentText 


»»-aDialogControl^TransparentText (--dc--)---------------------- >< 


The TransparentText method enables you to write text to а device context using WriteDirect in 
transparent mode, that is, without a white background behind the text. Restore the default mode using 
OpaqueText. 


Arguments: 


The only argument is: 


dc 


A device context. 


6.10.4. OpaqueText 


>>-aDialogControl~OpaqueText (--dc--)--------------------------- >< 


The OpaqueText method restores the default text mode, that is, with a white background behind the text, 
which overlays whatever is at that position in the dialog or dialog control. Use this method after 
transparent mode was set using TransparentText. 


Arguments: 


The only argument is: 


dc 


A device context. 
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6.10.5. WriteToWindow 


>>-aDialogControl~WriteToWindow(--hwnd-- ,--xPos-- ,--yPos-- ,--text--> 
>--+-------------------------------------- 4--------------------- > 
| +-"SYSTEM" -+ | 
+-,--+---------- +--+----------------- +-+ 
+-fontName-+ | *-10------- * | 
4-,--—---------- +-+ 


P RR +--)->< 
+-+---------------------------------------------------------------------- +-+ 
+-+------------------------------------------------------------------ +-+ 

| +----------------- + | 

| V *-ÜPAQUE------ + | | 

+-,--"----+-THIN-------- +-+--"--+-------------------------------- +-+ 
+-EXTRALIGHT--+ таен нн р-н +-+ 
*t-LIGHT------- * *-fgColor-* +-,--bkColor-+ 
*-MEDIUM------ * 


+-SEMIBOLD----+ 
+-EXTRABOLD---+ 


+-BOLD-------- + 
*-HEAVY------- * 
+-UNDERLINE---+ 
*-ITALIC------ * 


+-STRIKEQUT---+ 
+-TRANSPARENT-+ 
*-CLIENT------ * 


The WriteToWindow method enables you to write text to a dialog or dialog control in the given font and 
size to the given position. 


Arguments: 


The arguments are: 
hwnd 
The handle of the dialog or dialog control. See Get for how to get a valid handle. 


XPos, yPos 


The starting position of the text, in pixels. 


text 


The string you want to write to the dialog or dialog control. 


fontName 


The name of a font. If omitted, the SYSTEM font is used. 
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fontSize 


The size of the font. If omitted, the standard size (10) is used. 


fontStyle 


One or more of the keywords listed in the syntax diagram, separated by blanks: 


TRANSPARENT 


This style writes the text without clearing the background. 


OPAQUE 
This style, which is the default, clears the background with the given background color, or 
with white if the background color is omitted, before writing the text. 

CLIENT 


The device context of the dialog’s client area is used instead of the device context of the 
entire dialog. 


Example: 


This example writes the string "Hello world!" to the dialog window using a 24pt Arial font in bold 
and italic style: 


hwnd=MyDialog”Get 
MyDialog^WriteToWindow(hwnd, 23, 15, "Hello world!", 
"Arial", 24, "BOLD ITALIC") 


6.10.6. WriteToButton 


»»-aDialogControl^WriteToButton(--id--,--xPos--,--yPos--,--text--» 
»-—R-------------------------------------- 4--------------------- > 
| +-"SYSTEM" -+ | 
+-,--+---------- +--+----------------- +-+ 
+-fontName-+ | *-10------- * | 
4-,--—---------- +-+ 


»-—-------------------------------------------------------------------------- +--)->< 
+-+---------------------------------------------------------------------- +-+ 
+-+----------------------------------------------------------------—-- +-+ 

| +----------------- + | 

| V +-OPAQUE------ + | | 

+-,--"----+-THIN-------- +-+--"--+-------------------------------- +-+ 
+-EXTRALIGHT--+ +-,--+--------- +--+------------ +-+ 
*t-LIGHT------- * *-fgColor-* +-,--bkColor-+ 
*-MEDIUM------ * 


+-SEMIBOLD----+ 
+-EXTRABOLD---+ 
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*-BOLD-------- * 
*-HEAVY------- * 
+-UNDERLINE---+ 
*-ITALIC------ * 


+-STRIKEQUT---+ 
+-TRANSPARENT-+ 
*-CLIENT------ * 


The WriteToButton method enables you to write text to a button in the given font and size to the given 
position. 
Arguments: 


The arguments are: 


id 
The ID of a button. 


See WriteToWindow for a description of the other arguments. 


6.10.7. getTextSizeScreen 


»»--getTextSizeScreen(-text--4--------- +--+------------ +--+------------- +-)---->< 
+-,-type--+  *-,-fontSrc--* +-,-fontSize--+ 


Gets the size, width and height, in pixels, needed to display a string in a specific font. To calculate the 


size in dialog units use Ше getTextSizeDlg() method. 


Note: This method can only be used after the underlying Windows dialog has been created. In 
general this means in the initDialog() method or later in the life cycle of the dialog. If this method is 
invoked prior to the creation of the underlying dialog, a syntax error is rasised. 


Arguments: 


The arguments are: 


text 


The string whose size is desired. If none of the optional arguments are specified then the font 
in use by this object (dialog or dialog control object) is used to calculate the size. 
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type 


Optional. However, if any of the optional arguments are used this argument is required. It 
signals what fontSrc is. The allowed types are: 


Indirect 
fontSrc is a font name and fontSize is the size of the font. The calculation is done 


indirectly by temporarily obtaining a logical font using these parameters. 


DC 


fontSrc is a handle to a device context. The correct font for the calculation must already 
be selected into this device context. fontSize is ignored. See the getDC() and fontToDCQ) 
methods for information on obtaining a device context and selecting a font into it. 


Font 


fontSrc is a handle to a font. fontSize is ignored. 


Only the first letter of type is needed and case is not significant. 


fontSrc 


Optional. The source of the font to use in calculating the size. This argument object must 
match the type specification. It can be either a string, (a font name,) a hand to a device context, 
or a handle to a font. 


fontSize 


Optional. The size of the font. This argument is always ignored unless the type argument is 
Indirect. If type is Indirect and this argument is omitted then the defualt font size is used. 
(Currently the default size is 8.) 


Return value: 


The size needed for the string is returned in a Size object. The size is specified in pixels. 


Example: 


This example uses 2 static controls to display two strings. The static controls are positioned so that 
the second string immediately follows the first string. The size calculated is based on the font 
currently in use by the controls. The calculation is correct no matter what font is in use by the 
controls, even if the two controls use different fonts. (This is a contrived example, it was used for 
testing. Instead of having a space character in between the 2 strings, the ending "t" and the 


won 


beginning "a" are positioned with no space between them.) 


stFonti = self^getStaticControl(IDC ST. FONT1) 
stFont2 = self^getStaticControl(IDC. ST FONT2) 


size - stFonti^getTextSizeScreen("San Diego is great") 
stFonti^setText("San Diego is great") 
stFonti^setRect(1, 1, size^width, size^ height) 


nextX = 1 + size^width + 1 


size = stFont2^getTextSizeScreen("and ooRexx is the best") 
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stFont2~setText ("and ooRexx is the best") 
stFont2^setRect(nextX, 1, size^width, size^ height) 


6.10.8. setFont 


»»--setFont(--fontHandle--4--------- 4--)------------------------- >< 
+-,redraw-+ 


The setFont method assigns another font to be used for the text in a dialog or dialog control. 


Arguments: 


The arguments are: 


fontHandle 
The handle to the font that is to be used by the dialog or dialog control. There are several 
methods to get the font handle, including createFontEx() or getFont(). 

redraw 


Optional, „пие or .false. If you specify .true, the message sent to the underlying dialog or 
dialog control tells it to redraw itself. If you specify .false, the dialog or dialog control is not 
told to redraw itself. The default is .true. 


Return value: 
This method always returns 0. 


Example: 


The following example creates the font Arial with a size of 14 and assigns it to the tree view control 
FILES, which is forced to be redrawn. 


hfnt = Mydialog^createFontEx("Arial", 14) 
MyDialog”~ getTreeControl ("FILES") ~setFont(hfnt, .true) 


6.10.9. getFont 
as 17) a aaa a am >< 
Retrieves a handle to the font currently being used by the dialog or dialog control. 
Arguments: 

There are no arguments for this method 


Return value: 


This method returns a handle to the font for text used by the dialog or dialog control. 
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Example: 


This is an example from a fictious program where a custom font is used to emphasis the text in two 
static controls. When the user does some action, the text in one control is emphasised and the other 
is de-emphsised. One way to do this is to just swap the fonts. 


::method onToggle private 
statici = self^getStaticControl(IDC. 5Т OUTSTANDING, BLANCE) 
static2 = self^getStaticControl(IDC, ST LASTPAYMENT) 


fonti - statici^getFont 
font2 = static2"getFont 
static1l~setFont (font2) 
static2~setFont (font1) 


6.10.10. createFont 


»»--createFont(--4---------- *-—R------------ +-+--------- +-+------------- +--)---->< 
+-fontName-+ +-,-fontSize-+ +-,-style-+ +-,-fontWidth-+ 
The createFont method creates a font and returns its handle. 


Note the implementation of this method is incorrect. It does not return the font specified. The correct 
method to use is createFontEx(). createFont() is maintained for program compatibility. Some existing 
programs may rely on using the (incorrect) font returned. 


Arguments: 


The arguments are: 
fontName 
Optional. The name of the font. the default is System. 


fontSize 


Optional. The size of the font. The default is 10. 


style 
Optional. One or more of the following keyword, separated by blanks. 
THIN EXTRALIGHT LIGHT 
MEDIUM  SEMIBOLD EXTRABOLD 
BOLD HEAVY UNDERLINE 


ITALIC STRIKEOUT 


fontWidth 


Optional. The average width of the characters in the font. If omitted, the width is set to the 
value of fontSize. 
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6.10.11. createFontEx 


»»--createFontEx(--fontName-4-------------- *--—--------------- 4--)------------- >< 
+-,-pointSize--+ +-,-additional--+ 


Creates a logical font with the characteristics requested. This should be the preferred method to create 
fonts in ooDialog. The createFont() method does not properly create the font requested. 


The returned font can be used in any method that takes а font, such as, setFont(), setItemFont(), or 
fontToDC(). When the programmer is done with the font, the operating system resources used by the 
font can be released with the deleteFont() method. 


The Windows operating system uses a font mapper to map a logical font to the characteristics of the font 
requested. Because available fonts can vary from system to system, the returned font is not always the 
same as the requested font. For example, if a font named Palatino is requested, but no such font is 
available on the system, the font mapper will substitute a font that has similar attributes but a different 
name. 


The interface to the font mapper takes a wide range of arguments to specify many different attributes of 
the requested font. The additional argument gives the ooRexx programmer the ability to use any, or all, 
of these arguments. On the other hand, The createFontEx() method has good defaults for each of the 
arguments, allowing the programmer to use the method with a minimum of effort. 


If an application will run on different systems, where the programmer does not know in advance what 
fonts will be available on each system, carefully specifying the font characteristics will help give the 
application the same look on each system. The font mapper will pick a font on each system that most 
closely matches the requested attributes. 


Details 


This method provides an interface to the Win32 API: CreateFont (). Use the MSDN library 
documentation to get more information on the arguments to this method. 


Sets the .SystemErrorCode variable. 


Raises syntax errors when incorrect arguments are detected. 


Arguments: 


The arguments are: 


fontName 


The typeface name of the requested font. The fonts folder, accessed from the Control Panel, on 
Windows lists the typeface names of all fonts installed on the system. 


As noted above, the font mapper will try to substitute a similar font if the typeface name does 
not match any of the installed fonts. 


pointSize 


Optional. The point size of the requested font. The default is 8. 
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additional 


Optional. A .Directory object whose indexes define additional characteristics of the requested 


font. For any missing index, the default value is used for that characteristic. If this argument is 
omitted then the default value for all characteristics is used. 


The indexes are listed below. Each index maps to an argument of the Win32 API, 
CreateFont(). As suggested above, the programmer should consult the MSDN library 
documentation to get complete information on the individual arguments. The value for each 


index must be either numeric or logical, depending on the index. 


The indexes below are listed in the same order as the arguments to CreateFont () from nWidth 
to fdwPitchAndFamily. Where an index has a link, the link provides some more information on 
the possible values for index. The valid indexes are: 


Index 
WIDTH 


ESCARPMENT 


ORIENTATION 


WEIGHT 

ITALIC 
UNDERLINE 
STRIKEOUT 
CHARSET 
OUTPUTPRECISION 
CLIPPRECISION 


QUALITY 
PITCHANDFAMILY 


Return value: 


Meaning 


The average width of the 
characters in the requested 
font 


The angle between the 
escapement vector and the 
x-axis of the device 


The angle between each 
character's base line and the 
x-axis of the device 


The weight of the font 

True for an italic font 

True for an uderlined font 
True for a strikeout font 
Specifies the character set 
Specifies the output precision 
Specifies the clipping 
precision 

Specifies the output quality 


Specifies the pitch and family 
of the font 


Default 
0 


FW NORMAL 

false 

false 

false 

DEFAULT CHARSET 
OUT TT PRECIS 

CLIP DEFAULT PRECIS 


DEFAULT QUALITY 
FF_DONTCARE 


The return is a handle to a font that can be used in any ooDialog method that requires a font handle. 
Because of the way the font mapper works, it is hard to conceive of a circustance where this method 
would fail. However, if it were to fail, the .SystemErrorCode variable would be non-zero. 


Example: 


This example creates a 16 point, italic, underlined, Ariel font and then uses the font for a static 
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control. 


additional = .directory^new 
additional~italic = .true 
additional^underline = .true 


hFont = self~createFontEx("Arial", 16, additional) 
hOldFont = self^getStaticControl(IDC, ST ALERT)^setFont (hFont) 


This example creates a 14 point, bold, italic, Times New Roman font and instructs the font mapper 
to only choose from true type fonts. If there are no true type fonts installed on the system, then the 
font mapper returns to its default behavior. 

FW BOLD - 700 

OUT TT ONLY PRECIS - 7 


additional - .directory^new 

additional^italic - .true 

additional^weight = FW. BOLD 
additional^outputPrecison = OUT. TT . ONLY. PRECIS 


hFont = self^createFontEx("Times New Roman", 14, additional) 


6.10.11.1. createFontEx Argument Values 


The following list is the indexes of the .Directory object that can be used for the third argument of the 
createFontEx() method. The list provides additional information on the meaning of values that can be 
assigned to each index. 


width Must be an integer. 


Specifies the average width, in logical units, of the characters in the requested font. The default 
value of zero, tells the font mapper to choose a closest match value. This is likely to produce the 
best results, unless the programmer has some need that requires specifying the character width. 


The closest match value is determined by comparing the absolute values of the difference between 
the current device's aspect ratio and the digitized aspect ratio of available fonts. 

escarpment Must be an integer. 
Specifies the angle, in tenths of degrees, between the escapement vector and the x-axis of the 
device. The escapement vector is parallel to the base line of a row of text. Windows has no 
predefined values for this argument. 

orientation Must be an integer. 
Specifies the angle, in tenths of degrees, between each character's base line and the x-axis of the 
device. Windows has no predefined values for this argument. 

weight Must be an integer. 


Specifies the weight of the font in the range 0 through 1000. For example, 400 is normal and 700 is 
bold. If this value is zero, a default weight is used. The following table shows Windows predefined 
values for this argument: 
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Value Weight 
FW_DONTCARE 0 
FW_THIN 100 
FW_EXTRALIGHT 200 
FW_ULTRALIGHT 200 
FW_LIGHT 300 
FW_NORMAL 400 
FW_REGULAR 400 
FW_MEDIUM 500 
FW_SEMIBOLD 600 
FW_DEMIBOLD 600 
FW_BOLD 700 
FW_EXTRABOLD 800 
FW_ULTRABOLD 800 
FW_HEAVY 900 
FW_BLACK 900 








italic Must be a logical. 


Set this index to . true to request an italic font. The default is .false. 


underline Must be a logical. 


Set this index to . true to request an underlined font. The default is .false. 


strikeout Must be a logical. 


Set this index to . true to request a strike out font. The default is . false. 


charset Must be an integer. 


Specifies the character set. The following values are predefined in Windows: 



































Symbol Value 
ANSI_CHARSET 0 
BALTIC_CHARSET 186 
CHINESEBIG5_CHARSET 136 
DEFAULT_CHARSET 1 
EASTEUROPE_CHARSET 238 
GB2312_CHARSET 134 
GREEK_CHARSET 161 
HANGUL_CHARSET 129 
MAC_CHARSET 77 
OEM_CHARSET 255 
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Symbol Value 
RUSSIAN CHARSET 204 
SHIFTJIS_CHARSET 128 
SYMBOL_CHARSET 2 
TURKISH_CHARSET 162 
VIETNAMESE_CHARSET 163 








outputPrecsion Must be an integer. 


The output precision defines how closely the output must match the requested font’s height, width, 
character orientation, escapement, pitch, and font type. 


Applications can use the OUT_DEVICE_PRECIS, OUT_RASTER_PRECIS, OUT_TT_PRECIS, 
and OUT_PS_ONLY_PRECIS values to control how the font mapper chooses a font when the 
operating system contains more than one font with a specified name. For example, if an operating 
system contains a font named Symbol in raster and TrueType form, specifying OUT_TT_PRECIS 
forces the font mapper to choose the TrueType version. Specifying OUT_TT_ONLY_PRECIS 
forces the font mapper to choose a TrueType font, even if it must substitute a TrueType font of 
another name. 


It can be one of the following values: 














Symbol Meaning Value 
OUT CHARACTER PRECIS Not used. 2 
OUT DEFAULT PRECIS Specifies the default font mapper behavior. 0 
OUT DEVICE PRECIS Instructs the font mapper to choose a Device 5 


font when the system contains multiple fonts 
with the same name. 








OUT OUTLINE PRECIS This value instructs the font mapper to choose 8 
from TrueType and other outline-based fonts. 
OUT PS ONLY PRECIS Instructs the font mapper to choose from only 10 


PostScript fonts. If there are no PostScript fonts 
installed in the system, the font mapper returns 
to default behavior. 





OUT RASTER PRECIS Instructs the font mapper to choose a raster font 6 
when the system contains multiple fonts with 
the same name. 











OUT STRING PRECIS Not used. 1 
OUT STROKE PRECIS Not used. 
OUT TT ONLY PRECIS Instructs the font mapper to choose from only 


TrueType fonts. If there are no TrueType fonts 
installed in the system, the font mapper returns 
to default behavior. 
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Symbol Meaning Value 


OUT_TT_PRECIS Instructs the font mapper to choose a TrueType 4 
font when the system contains multiple fonts 
with the same name. 

















clipPrecision Must be an integer. 


The clipping precision defines how to clip characters that are partially outside the clipping region. It 
can be one or more of the following values. Use .DlgUtil-or to combine values. 














Symbol Meaning Value 
CLIP CHARACTER PRECIS | Not used. 1 (0x01) 
CLIP DEFAULT PRECIS Specifies default clipping behavior. 0 (0x00) 
CLIP DFA, DISABLE Windows XP SP1: Turns off font association 64 (0x40) 


for the font. Note that this flag is not guaranteed 
to have any effect on any platform after 
Windows Server 2003. 











CLIP EMBEDDED You must specify this flag to use an embedded 128 (0x80) 
read-only font. 
CLIP LH. ANGLES When this value is used, the rotation for all 16 (0x10) 


fonts depends on whether the orientation of the 
coordinate system is left-handed or 
right-handed. If not used, device fonts always 
rotate counterclockwise, but the rotation of 
other fonts is dependent on the orientation of the 
coordinate system. For more information about 
the orientation of coordinate systems, see the 
description of the orientation parameter. 




















CLIP MASK Not used. 15 (0xOf) 
CLIP STROKE PRECIS Not used. 2 (0x02) 
CLIP TT ALWAYS Not used. 32 (0x20) 








quality Must be an integer. 


The output quality defines how carefully the font mapper must attempt to match the logical-font 
attributes to those of an actual physical font. 


Note that if neither ANTIALIASED QUALITY nor NONANTIALIASED QUALITY is selected, 
the font is antialiased only if the user chooses "smooth screen fonts" in Control Panel. Quality can 
be one of the following values: 














Symbol Meaning Value 
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Symbol Meaning Value 





ANTIALIASED_QUALITY Font is antialiased, or smoothed, if the font 4 
supports it and the size of the font is not too 
small or too large. 





CLEARTYPE_QUALITY If set, text is rendered (when possible) using 6 
ClearType antialiasing method. See Remarks for 
more information. 





DEFAULT_QUALITY Appearance of the font does not matter. 0 





DRAFT_QUALITY Appearance of the font is less important than 
when the PROOF_QUALITY value is used. For 
GDI raster fonts, scaling is enabled, which 
means that more font sizes are available, but the 
quality may be lower. Bold, italic, underline, 
and strikeout fonts are synthesized, if necessary. 








NONANTIALIASED QUALITY Font is never antialiased, that is, font smoothing 3 
is not done. 
PROOF_QUALITY Character quality of the font is more important 2 


than exact matching of the logical-font 
attributes. For GDI raster fonts, scaling is 
disabled and the font closest in size is chosen. 
Although the chosen font size may not be 
mapped exactly when PROOF_QUALITY is 
used, the quality of the font is high and there is 
no distortion of appearance. Bold, italic, 
underline, and strikeout fonts are synthesized, if 








necessary. 











pitchAndFamily Must be an integer. 


Specifies the pitch and family of the font. Font families describe the look of a font in a general way. 
They are intended for specifying fonts when the exact typeface requested is not available. 


Combine one pitch value with one family value. The values are combined using a boolean or, but in 
this case they could simply be added. The programmer can also use .DlgUtil~or to combine values. 



































Symbol Meaning Value 
Pitch 

DEFAULT_PITCH 0 
FIXED_PITCH 

VARIABLE PITCH 2 
Family 

FF DECORATIVE Novelty fonts. Old English is an example. 128 (0x80) 
FF DONTCARE Use default font. 4 (0x04) 
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Symbol Meaning Value 

FF_MODERN Fonts with constant stroke width, with or without 32 (0x20) 
serifs. Pica, Elite, and Courier New are examples. 

FF_ROMAN Fonts with variable stroke width and with serifs. MS 8 (10x08) 
Serif is an example. 

FF_SCRIPT Fonts designed to look like handwriting. Script and 64 (0x40) 
Cursive are examples. 

FF_SWISS Fonts with variable stroke width and without serifs. 16 (0x10) 
MS Sans Serif is an example. 














6.10.12. deleteFont 


>>-aDialogControl~deleteFont (--hFont--)------------------------ >< 


The deleteFont method deletes a font. This method is to be used to delete a font created with the 
createFontEx() method. 


Arguments: 


The only argument is: 


hFont 
The handle of a font. 


6.10.13. FontToDC 


»»-aDialogControl^FontToDC(--dc--,hFont--)--------------------- >< 


The FontToDC method loads a font into a device context and returns the handle of the previous font. Use 
the GetWindowDC, GetDC, or GetButtonDC method to retrieve a device context, and the createFontEx() 
method to get a font handle. To reset the font to the original state, use another FontToDC call with the 
handle of the previous font. To release the device context, use the FreeWindowDC, FreeDC, or 
FreeButtonDC method. 


Arguments: 


The arguments are: 


dc 


The device context of a dialog or button. 
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hFont 
The handle of a font. 


Example: 
This example loads an Arial font into the current dialog window: 


additional = .directory^new 

additional^italic = .true 

hfnt MyDialog^createFontEx("Arial", 16, additional) 
dc MyDialog^GetDC 

oldf = MyDialog^FontToDC(dc,hfnt) /* activate font */ 


MyDialog^FontToDC(dc,oldf) /* restore previous font */ 
MyDialog^FreeDC(dc) 


6.10.14. FontColor 


»»-aDialogControl^FontColor(--color--,dc--)-------------------- >< 


The FontColor method sets the font color for a device context. 


Arguments: 


The arguments are: 


color 


The index of a color in the system’s color palette. 


dc 


The device context. 


6.11. Graphic Methods 


These methods deal with drawing graphics within the device context of a window. See GetWindowDC, 
GetDC, and GetButtonDC for information on how to retrieve a device context. 


6.11.1. CreateBrush 


»»-aDialogControl^CreateBrush(--color--4----------------- +--)-->< 
+-,brushSpecifier-+ 
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The CreateBrush method creates a color brush or a bitmap brush. It returns the handle to a brush object. 
To remove the brush, use DeleteObject. The brush is used to fill rectangles. 


Arguments: 


The arguments are: 


color 
The color number. For a list of color numbers, refer to Definition of Terms. 


brushSpecifier 


The name of a bitmap file or one of the following keywords to create a hatched brush: 


UPDIAGONAL 
A 45-degree upward, left-to-right hatch 


CROSS 


A horizontal and vertical crosshatch 


DIAGCROSS 
A 45-degree crosshatch 


DOWNDIAGONAL 
A 45-degree downward, left-to-right hatch 


HORIZONTAL 


A horizontal hatch 


VERTICAL 
A vertical hatch 


If CreateBrush is sent to a dialog object (subclass of ResDialog), brushSpecifier can also be an 
integer resource ID for a bitmap stored in the DLL that also stores the resource. 


If this argument is omitted, a solid brush with the specified color is created. 


6.11.2. CreatePen 


+-1----- + 
»»-aDialogControl^CreatePen(--4------- 4--,--4---------------------- +--,--> 
+-width-+ | *-SÜLID------ * | 
+-"--+-DASH------- +--"-+ 
+-DOT-------- + 


+-DASHDOT----+ 
+-DASHDOTDOT-+ 
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+-со10г-+ 


The CreatePen method creates a pen in Ше specified color and style. It returns Ше handle to a pen object. 
To remove the pen, use DeleteObject. 


Arguments: 


The arguments are: 
width 
The width of the lines that the pen will draw. If omitted, 1 is used as default. 


style 


One of the keywords listed in the syntax diagram. Values other than SOLID or NULL have no 
effect on pens with a width greater than 1. SOLID is the default. 


color 


The color number of the pen. If omitted, 0 is used as default. For a list of color numbers, refer 
to Definition of Terms. 


Example: 
The following example creates a dotted pen object with a width of 1: 


hPen = MyDialog~CreatePen(1, "DOT", 13) 


6.11.3. ObjectToDC 


>>-aDialogControl*O0bjectToDC (--dc-- , --obj--) ------------------- >< 


The ObjectToDC method loads a graphic object, namely a pen or a brush, into a device context. 
Subsequent lines, rectangles, and arcs are drawn using the pen and brush. 


Arguments: 


The arguments are: 


dc 


The device context. 


obj 


The object: a pen or a brush. 
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Return value: 


The handle of the previous active pen or brush. It can be used to restore the previous environment. 


Example: 
The following example activates a pen for drawing: 


ас = MyBaseDialog~GetDC 
hpen = MyDialog^CreatePen(2, "SOLID", 4) 
MyDialog~O0bjectToDC (dc, hpen) 

. /* do lines, rectangles, ... */ 
MyDialog~delete0bject (преп) 


6.11.4. DeleteObject 


>>-aDialogControl~Delete0bject (--obj--) ------------------------ >< 


The DeleteObject method deletes a graphic object, namely a pen or a brush. See CreatePen and 
CreateBrush for information on how to get the handle of a pen or brush. 


Arguments: 


The only argument is: 


obj 
The handle of a pen or brush. 


6.12. Graphic Drawing Methods 


The following methods are used to draw rectangles, lines, pixels, and arcs in a device context. See 
GetWindowDC, GetDC, and GetButtonDC for how to retrieve a device context. A pen and a brush can 
be activated using ObjectToDC before invoking the drawing methods. 


Note: Because the pixel values include the title bar in a dialog it is easier to define a button filling the 
window, and then draw on the button. 


6.12.1. Rectangle 


»»-aDialogControl^Rectangle(--dc--,--x--,--y--,--x2--,--y2--*----------- +--)->< 
+-,--"FILL"-+ 
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The Rectangle method draws a rectangle to the given device context. The appearance is determined by 
the graphics objects currently active in the device context. The active pen draws the outline and, 
optionally, the active brush fills the inside area. The default pen is thin black and the default brush is 
white. 


Arguments: 


The arguments are: 


dc 


The device context. 


X, y 


The position of the upper left corner of the rectangle, in pixels. 


x2, y2 


The position of the lower right corner. 


"FILL" 


The rectangle is filled with the active brush. 


Example: 


The following example draws a red rectangle filled with yellow, surrounded by a black rectangle: 


dc = self~getButtonDC (100) 

brush = self~createBrush(15) /* yellow */ 
pen = self~createPen(10,"solid",13) /* thick red */ 
oldb = self~objectToDC(dc, brush) 

oldp = self^objectToDC(dc,pen) 

self~Rectangle(dc, 50, 50, 200, 150, "FILL") 
self^objectToDC(dc,oldp); self^deleteObject (pen) 
self^objectToDC(dc,oldb); self~deleteObject (brush) 
self~Rectangle(dc, 40, 40, 210, 160) /* default */ 


6.12.2. DrawLine 


»»-aDialogControl^DrawLine(--dc--,--4-------4--,--*-------*--,--toX--,--toY--)-»« 
+-fromX-+ +-fromY-+ 


The DrawLine method draws a line within the device context using the active pen. 
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Arguments: 
The arguments are: 
dc 


The device context. 


fromX, fromY 


The starting position, in pixels. If omitted, the previous end point of a line or arc is used. 


toX, toY 


The target position. 


6.12.3. DrawPixel 


»»-aDialogControl^DrawPixel(--dc--,--x--,--y--,--color--)------ >< 


The DrawPixel method draws a pixel within the device context. 


Arguments: 


The arguments are: 


йс 


The device context. 


х,у 


The position, in pixels. 


color 


The color number for the pixel. For a list of color numbers, refer to Definition of Terms. 


6.12.4. GetPixel 


»»-aDialogControl^GetPixel(--dc--,--x--,--y--)----------------- >< 


The GetPixel method returns the color number of a pixel within the device context. 
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Arguments: 


The arguments are: 


dc 


The device context. 


х,у 


The position, in pixels. 


6.12.5. DrawArc 


»»-aDialogControl^DrawArc(--dc--,--x--,--Y--,--x2--,--y2-------- > 
»-—R---------------------------------------- 4--)--------------- >< 
+-,--startx--,--starty--,--endx-- ,--endy-+ 


The DrawArc method draws a circle or ellipse on the given device context using the active pen for the 
outline. The circle or ellipse is drawn within the boundaries of an imaginary rectangle whose coordinates 
are given. A partial figure can be drawn by giving the end points of two radials. By default, the figure is 
drawn counterclockwise, but the direction can be modified using SetArcDirection. 


Arguments: 


The arguments are: 


dc 

The device context. 
X,y 

The position of the upper left corner of the imaginary rectangle, in pixels. 
x2, y2 


The position of the lower right corner of the imaginary rectangle, in pixels. 


startx, starty, endx, endy 


The end points of the starting and ending radials for drawing the figure. A full circle or ellipse 
is drawn if no start and end are given. Omitted values default to 0. Imaginary radials are drawn 
from the center to the start and end points. The circle or ellipse is then drawn between the 
intersections of these lines with the full circle or ellipse. 


Example: 
This example draws a full ellipse and a quarter circle: 


dc = self^getButtonDC(100) 
pen = self^createPen(4,"solid",13) 
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oldp = self^objectToDC(dc,pen) 
self~drawArc(dc,50,50, 200,150) /* full ellipse */ 


self~drawArc(dc,100,100,150,150, 200,50,75,75) /* quarter circle */ 
self^objectToDC(dc,oldp); self^deleteObject (pen) 


6.12.6. GetArcDirection 


»»-aDialogControl^GetArcDirection(--dc--)---------------------- >< 


The GetArcDirection method returns the current drawing direction for the DrawArc method. 


Arguments: 


The only argument is: 


йс 


The device context. 


6.12.7. SetArcDirection 


>>-aDialogControl~SetArcDirection(--dc-- ,--"--+-COUNTERCLOCKWISE-+--"--)->< 
+-CLOCKWISE-------- + 


The SetArcDirection method changes the drawing direction for the DrawArc and DrawPie methods. 


Arguments: 


The arguments are: 


dc 


The device context. 


direction 


The new drawing direction. 


6.12.8. DrawPie 
>>-aDialogControl~DrawPie(--dc-- ,--x-- ,--y-- ,--x2-- ,--y2--> 


»--,--startx--,--starty--,--endx--,--endy--)------------- >< 
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The DrawPie method draws a pie of a circle or ellipse on the given device context using the active pen 
for the outline and the active brush to fill the pie. The circle or ellipse is drawn within the boundaries of 
an imaginary rectangle whose coordinates are given. The arc is drawn between start and end radials in 
the direction specified by SetArcDirection. 


Arguments: 


The arguments are: 


dc 

The device context. 
X,y 

The position of the upper left corner of the imaginary rectangle, in pixels. 
x2, y2 


The position of the lower right corner of the imaginary rectangle. 


startx, starty, endx, endy 


The end points of the two radials (same as for DrawArc). 


6.12.9. FillDrawing 


»»-aDialogControl^FillDrawing(--dc--,--x--,--y--,--color--)----5« 


The FillDrawing method fills an outline figure in the given device context using the active brush. 


Arguments: 


The arguments are: 


dc 


The device context. 


X,y 
The inside starting position for filling the outline figure with the color of the brush, in pixels. 


color 


The color number of the outline figure whose inside will be filled. For a list of color numbers, 
refer to Definition of Terms. 


ooRexx OODialog Reference Version 4.0.0 269 


Chapter 6. DialogControl Class 
6.12.10. DrawAngleArc 
>>-aDialogControl~DrawAngleArc (--dc-- ,--xs-- ,--ys-- ,--x-- ,--y--> 
»--,--radius--,--startangle--,--sweepangle--)----------------- >< 
The DrawAngleArc method draws a partial circle (arc) and a line connecting the start drawing point with 


the start of the arc on the given device context using the active pen for the outline. The circle is drawn 
counterclockwise with the given radius between the given angles. 


Arguments: 


The arguments are: 
dc 
The device context. 


XS, yS 


The start draw position, in pixels. 


X, y 


The center of the circle, in pixels. 


radius 


The radius of the circle, in pixels. 


startangle, sweepangle 


The starting and ending angles for the partial circle in degrees (0 is the x-axis). 
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The UserDialog class extends the BaseDialog class. It provides methods to create a dialog with these 
control elements: 


Entry lines 
Push buttons 
Check boxes 
Radio buttons 
List boxes 
Combo boxes 


Frames and rectangles 


Note: The class also inherits the methods of its parent class: the BaseDialog class. 


Subclasses of the UserDialog can inherit the mixin AdvancedControls class. This class provides methods 


to dynamically create a dialog with these additional elements: 


List controls (List-view controls) 
Tree controls 

Tab controls 

Slider controls 


Progress Bar controls 


There are three basic ways of creating a dialog using the UserDialog class: 


Load the dialog from a resource script using the Load method. This will create the dialog and its 
controls from the definitions in the resource script. An alternative to calling the Load method is to use 
the RcDialog class. This class is a subclass of the UserDialog class and provides a convenient way to 
create a dialog from a resource script. It handles the details of loading the resource script transparently 
and leaves the programmer free to concentrate on the details of the behavior of the dialog. 


Invoke Add... methods on an instance of this class or a subclass and create the dialog step by step, one 
method for one dialog item. The best place to invoke these Add... methods is to override the 
DefineDialog method. The DefineDialog method is called automatically when an instance of the 
UserDialog is created. 


In addition to creating dialog items one at a time, there are also methods that enable you to define a 
group of the same dialog elements together. The names of these methods begin with Add... and end 
with Group or Stem. 


Combine loading a dialog from a resource script and adding elements dynamically. This would define 
the dialog and some of the dialog controls using the resource script. The programmer could then 
define additional dialog controls using the Add... methods in the DefineDialog method. For instance, 
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this could be useful in an application that had several dialogs with similar features. The similar aspects 
of each dialog could be placed in a resource script and then the individual dialogs could be customized 
using the Add... methods. 


Requires: 
UserDlg.cls is the source file of this class. 
::requires "oodialog.cls" 

Subclass: 


The UserDialog class is a subclass of BaseDialog. 


Attributes: 


Instances of the UserDialog class have the following attributes: 


AktPtr 


An attribute for internal use 


BasePtr 


An attribute for internal use 


DialogItemCount 


An attribute for internal use 


FactorX 


Horizontal size of one dialog unit (in pixels) 


FactorY 


Vertical size of one dialog unit (in pixels) 


SizeX 
The width of the dialog, in dialog units, when the underlying Windows dialog object is created. 


Note: If the program creates a resizable dialog and the user changes the size of the dialog, this 
attribute is not updated by ooDialog. If the programmer requires that the SizeX attribute always 
reflects the actual size of the dialog, (for a resizable dialog,) then the programmer is 
responsible for updating its value when the size of the dialog changes. The programmer would 
use the ConnectResize method to receive notifications when the dialog changed size and 
update the attribute accordingly. 


SizeY 
The height of the dialog, in dialog units, when the Windows dialog object is created. 


Note: In a similar fashion to the SizeX attribute, the programmer would be responsible for 
updating this attribute for resizable dialogs. 
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Methods: 


Instances of the UserDialog class implement the methods listed in the following table. 


Table 7-1. UserDialog Instance Methods 

















































































































Method... ..оп page 
addBitmapButton addBitmapButton 
addBlackFrame addBlackFrame 
addBlackRect addBlackRect 
addButton addButton 
addButtonGroup addButtonGroup 
addCheckBox addCheckBox 
addCheckBoxStem addCheckBoxStem 
addCheckGroup addCheckGroup 
addComboBox addComboBox 
addComboInput addComboInput 
addEntryLine addEntryLine 
addEtchedFrame addEtchedFrame 
addGrayFrame addGreyFrame 
addGrayRect addGrayRect 
addGroupBox addGroupBox 
addEtchedHorizontal addEtchedHorizontal 
addIcon addIcon 

addInput addInput 
addInputGroup addInputGroup 
addInputStem addInputStem 
addListBox addListBox 
AddMenultem AddMenultem 
AddMenuSeparator AddMenusSeparator 
addOkCancelLeftBottom addOkCancelLeftBottom 
addOkCancelLeftTop addOkCancelLeftTop 
addOkCancelRightBottom addOkCancelRightBottom 
addOkCancelRightTop addOkCancelRightTop 
addPasswordLine addPasswordLine 
AddPopupMenu AddPopupMenu 
addRadioButton addRadioButton 
addRadioGroup addRadioGroup 
addRadioStem addRadioStem 
addStatic addStatic 
addScrollBar addScrollBar 
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Method... ..оп page 

addText addText 

addEtched Vertical addEtched Vertical 

addWhiteFrame addWhiteFrame 

addWhiteRect addWhiteRect 

Create Create 

CreateCenter CreateCenter 

CreateMenu CreateMenu 

DefineDialog DefineDialog 

Init Init 

InitAutoDetection InitAutoDetection 

Load Load 

LoadFrame LoadFrame 

LoadItems LoadItems 

LoadMenu LoadMenu 

SetMenu SetMenu 

StartIt StartIt 

Stoplt Stoplt 

7.1. Init 
»»-aUserDialog^Init(--4---------- *--—--------------- +--)------- >< 

+-,--headerFile-+ 


The Init method initializes a new dialog object. 


Arguments: 


The arguments are: 


DlgData. 


A stem variable that is used to initialize the data fields of the dialog. If the dialog is terminated 
by means of the OK button, the values of the dialog’s data fields are copied to this variable. 
The ID of the dialog items is used to name each entry within the stem. 


headerFile 


A file defining symbolic IDs for dialog resources. Symbolic IDs defined in the file can be used 
in method calls where resource IDs are required. 
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Example: 


The following example creates a new dialog object, adding any symbolic IDs defined in 
resources.h to the object’s ConstDir directory: 


MyDialog-.UserDialog^new(aStem., "resources.h") 


The example for the init method in the BaseDialog section shows the use of the dialog data stem 
and header file arguments in more detail. 


7.2. InitAutoDetection 


>>-aUserDialog” InitAutoDetection------------------------------- >< 


The InitAutoDetection method is called by the Init to determine whether or not automatic data field 
detection should be used. For a UserDialog, autodetection is disabled. 


Protected: 
This method is protected. It is called by the class itself and can be overwritten. 


Example: 


The following example overrides the method to switch off auto detection: 


::class MyClass subclass UserDialog 


::method InitAutoDetection 
self^NoAutoDetection 


7.3. Create 


»»-aUserDialog^Create(--x--,--y--,--cx--,--cy--,--title--,------ > 
>--+--------------------------- +-- --+---------- +--------------- > 
| ERE E : | +-dlgClass-+ 
| V | | 
+-"----+-NOMENU------+-+--"=-+ 
*-VISIBLE----- + 
+-NOTMODAL----+ 
+-SYSTEMMODAL-+ 
+-THICKFRAME--+ 
+-MINIMIZEBOX-+ 
+-MAXIMIZEBOX-+ 
>---+---------- + --#5--------<- в-ва +--)-------- >< 
+-fontName-+ +-fontSize-+ +-expected-+ 
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The Create method creates the Windows dialog you previously defined with Add... methods. You can set 


the size, title, and style of the dialog. If the return code of Create is 0 the dialog creation failed and you 
should not try to execute the dialog object. 


Arguments: 


The arguments are: 


х,у 
The position of the upper-left edge of the dialog in dialog units 
CX, cy 
The extent (width and height) of the dialog in dialog units 
title 
The dialog’s title that is displayed in the title bar 
options 


One or more of the keywords listed in the syntax diagram, separated by blanks: 


NOMENU 

Creates a dialog without a system menu 
VISIBLE 

Creates a visible dialog 
NOTMODAL 

Creates a dialog with a normal window frame 
SYSTEMMODAL 

Creates a dialog that blocks all other windows 
THICKFRAME 

Creates a dialog with a thick frame 
MINIMIZEBOX 


Creates a dialog with a minimize button. 


MAXIMIZEBOX 


Creates a dialog with a maximize button. 


digClass 


Name of the window class used for the dialog. This argument must be omitted or an empty 
string. 
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fontName 


The name of a font used by the dialog for all text. The default font is System. 


fontSize 


The size of the font used by the dialog. The default value is 8. 


expected 


This argument determines the maximum number of dialog elements (static text, entry lines, list 
boxes, and the like) the dialog can handle. The default value is 200. If your dialog has more 
than 200 elements, you must set this value; otherwise, the dialog fails. 


Example: 


The following example creates a dialog with a size of 300 by 200 dialog units. The dialog has no 
system menu in its upper-left corner. It has a thick frame (therefore the dialog will get resizable) and 
a 12-point font. The dialog has capabilities for up to 100 elements. 
rc = MyDialog^Create(20, 20, 300, 200, "My first Dialog", , 

"THICKFRAME NOMENU", , "Courier", 12, 100) 
if rc <> 0 then MyDialog^Execute 


7.4. CreateCenter 


»»-aUserDialog^CreateCenter(--cx--,--cy--,--title--,------------ > 
>--+--------------------------- +-- --+---------- +--------------- > 
| EL EIE EE А | +-dlgClass-+ 
| V | | 
+-"----+-NOMENU------+-+--"-+ 
+-VISIBLE----- + 


+-NOTMODAL----+ 
+-SYSTEMMODAL-+ 
+-THICKFRAME--+ 
+-MINIMIZEBOX-+ 
+-MAXIMIZEBOX-+ 


"RR 4--)-------- >< 
*t-,--fontName--4------------------------------ +-+ 
T2,--fOntSize--t------------- +=+ 


+-,--expected-+ 


The CreateCenter method creates a dialog and centers its position. See Create for a description of all 
arguments and an example. 
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7.5. DefineDialog 


»»-aUserDialog^DefineDialog------------------------------------ >< 


The DefineDialog method is called by Create. It is designed to be overwritten in a subclass of 
UserDialog. You should do all the definition of dynamically added dialog controls within this method, 
using the Add... Methods. 


Protected: 


This method is protected. There is no need to call this method from anywhere else than Create. 


Example: 
When the dialog is created, a push button and an entry line are added to its client area: 


::class MyDialog subclass UserDialog 


::method DefineDialog 
self~addButton(401, 20, 235, 40, 15, "&More...") 
self~addEntryLine(402, INPUT_1, 20, 170, 150, 10) 


7.6. Load 


»»-aUserDialog^Load(--resourceFileName--,--dialogId------------- ? 
B-—R------------------------------------------------------ +----- > 
+-,--+----------------------------—-- 4+--+------------- +-+ 
| е ысышын шысы ышыгы Е | +-,--expected-+ 
| V | | 
qct---—E-CENTER--———-—-—-- «ce 


+-CONNECTBUTTONS-+ 

+-CONNECTRADIOS--+ 

+-CONNECTCHECKS--+ 
»--)----------------------------------------------------------- >< 


The Load method creates the dialog based on the data of a given resource script (a file with the extension 
.RC). It calls the LoadFrame and LoadItems methods to retrieve the dialog data from the file. 


Return code: 


The return code is 0 for a successful load and | otherwise 
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Arguments: 


The arguments are: 


resourceFileName 


The name of the resource script of the dialog 


dialoglId 
The ID (number) of the dialog. Note that each dialog has a unique ID assigned to it. There can 
be more than one dialog definition in one resource file. If there is only one dialog resource in 
the resource file, you do not have to indicate the ID. 

options 


One or more of the keywords listed in the syntax diagram, separated by blanks: 


CENTER 


The dialog is positioned in the center. 


CONNECTBUTTONS 


For each button a connection to an object method is established automatically. See 
ConnectControl for a description of connecting buttons to a method. 


CONNECTRADIOS 
Similar to CONNECTBUTTONS, this option enforces the method to connect the radio 
buttons. 

CONNECTCHECKS 


This option connects the check box controls. 


expected 


This is the maximum number of dialog elements the dialog object can handle. See Create. 


Example: 


The following example creates a dialog based on the values for dialog 100 in Dialogi.rc. It also 
connects the push and radio buttons to a message named after the buttons’ title. 


MyDlg = .UserDialog^new() 
MyDlg^Load("Dialogi.rc", 100, "CONNECTBUTTONS CONNECTRADIOS") 


7.7. LoadFrame 


»»-aUserDialog^LoadFrame(--resfile------------------------------ ? 
>--+-------------------------------------------------------+---- > 
+-,--+---------- +--+---------------------------------- +-+ 
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*-dialogid-* +-,--+---------- +--+------------- +-+ 


+-"CENTER"-+ +-,--expected-+ 


Da) SS ss SS eee cs >< 


The LoadFrame method creates the window frame using the data of the given dialog resource with 
dialogid in file resfile. It is usually called by the Load method. 


Protected: 
This method is protected. It can only be used internally within a class method. 


Arguments: 


The arguments are: 


resfile 
The name of the resource file 
dialogid 


The ID of the dialog. It can be omitted if there is just one dialog; otherwise it has to be 
specified. 


expected 


The number of expected dialog items 


Example: 


The following example overrides the Load method, so it loads the dialog window (just the frame) 
but not its contents: 


::class WindowOnlyDialog subclass UserDialog 


::method Load 
self~LoadFrame("Dialog2.rc", 100, "CENTER", 20) 


7.8. Loaditems 


»»-aUserDialog^LoadItems(--resFile------------------------------ 


*-dialogId-* | --------<--+- ; | 
| ү | | 
+-, --"----+-CONNECTBUTTONS-+-+--"-+ 

+-CONNECTRADIOS--+ 
+-CONNECTCHECKS--+ 
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The LoadItems method creates the dialog items, using the data of the given resource script. It is either 
called by the Load method, or it can be used in the context of a category dialog. 


Protected: 


This method cannot be called from outside the class. 


Arguments: 


See Load for a description. 


Example: 


In the following example the dialog is created either with the items of dialog 200 or dialog 300, 
depending on the argument: 


::class MyDialog subclass UserDialog 


::method Load 
use arg view 
self~LoadFrame("Dialog2.rc", 200, "CENTER", 200) 
if view="special" then 
self~LoadItems("Dialog2.rc", 200, "CONNECTBUTTONS") 
else 
self~LoadItems("Dialog2.rc", 300, "CONNECTBUTTONS") 


7.9. Add... Methods 


The methods listed below (all starting with Add) can be used to create a dialog dynamically without any 
resource script (.RC file). The methods are used to define the individual dialog controls. The methods can 
also be used in a dialog that is created by loading a resource script. The methods will then be used to 
define controls in addition to the ones defined in the resource script. 


The recommended way to create a dialog dynamically is to subclass from UserDialog and put all Add... 
statements into the DefineDialog method, which is executed when the dialog is about to be created. 


The Add... methods call the matching Connect... methods to create the associated Object Rexx attribute. 
Add... methods cannot be used after Execute has started. 


The behavior and appearance of all dialog controls created using one of the Add... methods are 
controlled by a style option. For each of the Add... methods, one of the arguments consists of a set of 
keywords that define the style of the control being defined. These keywords allow the programmer to 
change the default behavior and / or appearance of the control. 


An attempt is made for each method to list all the style keywords that will be accepted. However, the 
behaviour and appearance that the specified style gives any particular control is determined by the 
operating system, not ooDialog. For many of the dialog controls, certain combinations of styles do not 
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make much sense. It is up to the individual programmer to decide whether a style is appropriate for her 


program. 


There are five styles that all dialog controls share: 


Visible 
Enabled 
Border 
Group 
TabStop 


The following style keyword list explains these styles and how the keywords are used for the styles. In 
many cases, there is a common default value for the style and the programmer only needs to specify a 


keyword when she wants a non-default value for the style. For instance, normally all dialog controls are 
created enabled. The programmer would only need to specify the DISABLED keyword when the control 
should be disabled as the dialog is first displayed. 


HIDDEN 


All windows (and every dialog control is a window) can be visible or invisible. When a control is 
invisible it is not displayed on the screen and the user will not see it. The control is also not active 
and will not accept any keyboard or mouse input. But, the control still exists and does not lose any 
of its internal state. Since the control is invisible, whatever is underneath it will be displayed on the 
screen. Normally this would be the owner dialog. However, it could also be another dialog control. 
If this other dialog control is visible, the user will see and can interact with it rather than the 
invisible control. 


In ooDialog by default all controls created using the Add... methods will be created visible. To 
change the default for any control when using the Add... methods add the HIDDEN keyword to the 
style argument. This will make the control invisible when the dialog is first shown on the screen. 


For any control, the visible style can be changed during program execution by using the Hide or 
Show methods. (Or any of the related methods like HideFast, Display, etc..) 


DISABLED 


All windows can be disabled or enabled. When a dialog control is disabled it will not accept 
keyboard or mouse input and therefore the user can not interact with it. The operating system will 
draw disabled controls in a different manner than enabled controls to give the user a visual clue that 
the control is disabled. 


When using the Add... methods controls will be created enabled. To change this for any control add 
the DISABLED keyword to the style argument. The control will then be disabled when the dialog is 
first shown on the screen. 


All controls can have their enabled style changed during program execution by using the Disable or 
Enable methods. (Or any of the related methods like DisableItem, EnablelItem, etc..) 


BORDER, NOBORDER 


Most, but not all, windows are drawn with a border. When using the Add... methods individual 
controls are drawn by default with, or without, a border. The default is changed by using either the 
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BORDER or NOBORDER keywords. The reference for each individual Add... method notes the 
default for the control for this style and which keyword is used to change the default. In general, this 
style can not be changed after a control is created. 


GROUP 


This style is used to place a series of consecutive dialog controls in a group. The first control with 
the group style starts a new group of controls. This group continues for each control that does not 
have the group style. As soon as a successive control is encountered with the group style, a new 
group is started. This style is only meaningful for dialog control windows. 


The Windows dialog manager uses this style to determine the behavior of a dialog, mostly the 
navigation behavior. Within a group of controls the user navigates from one control to the other 
using the arrow keys rather than the tab key. 


The GROUP keyword is used to give a control the group style when it is created using one of the 
Add... methods. After the control has been created its group style can be changed during the 
execution of a dialog by using the SetGroup method of the PlainBaseDialog class or the Group 
method of the DialogControl class. 


TAB, NOTAB 


The tabstop style is another style that is only meaningful with dialog controls. When a control has 
the tabstop style the user can navigate to it using the tab key. If a control does not have this style, the 
tab key will skip over the control. Dialog controls in the same class usually all have the same style 
for tabstop. As an example, all button controls usually have the tabstop style, whereas all static text 
controls usually do not have the tabstop style. 


When a control as added to an UserDialog instance it is given the tabstop style that is normal for the 
control. The individual Add... methods document the default for the control. The programmer uses 
either the TAB or NOTAB keywords to change the default. After controls have been created they 
can have their tabstop style changed using the SetTabStop method of the PlainBaseDialog class or 
the TabStop method of the DialogControl class. 


All dialog controls have a position and size. The position of the control is specified by the coordinates of 
its upper left corner (x, y) and the size is specified by its width (cx) and height (cy). Windows uses a 
coordinate system that specifies the upper left corner of the screen as (0,0). Moving to the left in this 
system increases the x value and moving down increases the y value. Negative values for either x or y 
would then move off the screen. (Normally. This simple explanation becomes more complicated with 
dual-monitor systems.) 


Note: Unless otherwise stated, the coordinates (the x, y, cx, and cy arguments) of the dialog control 
definitions are specified in dialog units. 


Note: When dialog controls are defined, their position and size is specified in relation to the upper 
left corner of the dialog’s client window. Specifying the position relative to the screen would of course 
be meaningless as the dialog is moved around. 
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All the Add... Methods that create a single control have the following common arguments. Some of the 
other Add... Methods that create a group of controls will only take the postion, or the size arguments: 


x 
The left position of the control in the dialog’s client window, in dialog units. 
y 
The top position of the control in the dialog’s client window, in dialog units. 
cx 
The width of the control in dialog units. 
cx 
The height of the control in dialog units. 
id 


All dialog controls have a numeric resource ID. The ooDialog framework is designed to accept a 
symbolic ID anywhere a resource ID is needed. All the Add... methods accepted a symbolic ID for 
the id argument. 


By default static controls and group boxes are assigned a resource id of -1. However, assigning a 
positive id allows the programmer to modify the static control or group box after it is created, 
perhaps to change the text of its title, or to change its postition. Without a positive ID, a static 
control or group box can not be modified. Which is fine, normally static controls and group boxes 
do not need to be modified. 


7.9.1. Add Button Controls 


The methods in this section are all used to add button controls. Button controls include push buttons, 
radio buttons, check boxes, group boxes, and owner-drawn buttons. See the chapter on button controls 
for more information. 


7.9.1.1. addGroupBox 


»»-dlg^addGroupBox(--x-,-y-,-cx-,-cy--*--------- *----------- +-------- +--)----- >< 
*-,-text--t-,--style--*-,--id--* 


The addGroupBox method adds a group box to the dialog. A group box is a button control, not a static 
control. A group box can have a frame and a label 


Arguments: 


This method takes the following arguments. 


X, y, CX, су 


The control coordinates 
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text 


The text for the group box label 


style 


A list of 0 or more style keywords separated by spaces: 


RIGHT 


Normally the text is aligned to the upper left of the group box frame. This style aligns the 
text to the upper right of the frame 


HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 


BORDER 


The border window style. 


GROUP 
The group control style. 


TAB 


The tabstop control style. 


The resource ID for the group box. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


7.9.1.2. addButton 


»»--addButton(--id-,-x-,-y-,-cx-,-cy-,-*-------- +--+-------------- +--+--------- +-)-->< 
+-,-text-+ +-,-msgToRaise-+ +-,-style-+ 


ooRexx OODialog Reference Version 4.0.0 285 


Chapter 7. UserDialog Class 


The addButton method adds a push button to the dialog and optionally connects it with a method that is 
invoked whenever the button is clicked. 
Arguments: 
The arguments are: 
id 
The resource ID for the button. 
X, у, CX, су 
The control coordinates 
text 


Optional. The text for the label of the button. The default is the empty string. 


msgToRaise 


Optional. The name of a method of the dialog class that is to be invoked each time the button is 
clicked. This serves the same purpose as the connectButton() method. 


style 


A list of 0 or more of the following style keywords separated by spaces: 
DEFAULT HCENTER FLAT 


OWNER TOP HIDDEN 
BITMAP BOTTOM DISABLED 
ICON VCENTER BORDER 
LEFT MULTILINE GROUP 


RIGHT NOTIFY NOTAB 


DEFAULT 
The button becomes the default button in the dialog. 
OWNER 


The programmer is completely responsible for drawing the button when the dialog 
receives the WM_DRAWITEM message. Currently this would be difficult (but not 
impossible) to implement in ooDialog. A simpler approach for an owner drawn button is 
to use an image list with the button. See the setImageList() method. 


ICON 

The button displays an icon image. 
BITMAP 

The button displays a bitmap image. 
LEFT 


Left justifies the text in the button rectangle. If neither LEFT nor RIGHT are specified the 
text is centered in the button rectangle. 
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RIGHT 


Right justifies the text in the button rectangle. If neither LEFT nor RIGHT are specified 
the text is centered in the button rectangle. 


HCENTER 


The button has its text centered horizontally in the button rectangle. This is the default if 
neither LEFT nor RIGHT are specified. 


TOP 


The text is aligned at the top of the button rectangle. If neither TOP nor BOTTOM are 
specified the text is vertically centered in the button rectangle. 


BOTTOM 


The text is aligned at the bottom of the button rectangle. If neither TOP nor BOTTOM are 
specified the text is vertically centered in the button rectangle. 


VCENTER 


The text is vertically centered in the button rectanble. This is the default if neither TOP 
nor BOTTOM are specified. 


MULTILINE 


If the text for the label of the button is longer than the width of the button rectangle, the 
operating system will word wrap the text producing more than one line. The height of the 
button rectangle has to be sufficient to display the extra line(s) or the text is clipped. 


NOTIFY 


Enables the button to send notifications for the gained focus, lost focus, and double click 
events. This is only necessary when the connectButtonNotify method is used, and only for 
the GOTFOCUS, LOSTFOCUS, or DBLCLK keywords of that method. 


FLAT 


The button is drawn with a flat appearance, i.e., it is drawn as a flat rectangle the label text 
inside the rectangle. 


HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 


BORDER 


The border window style. 


GROUP 
The group control style. 
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NOTAB 


The no tabstop control style. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


The following example creates a push button entitled "Get new Info" at position x=100, y=80 and 
size width=40, height=15. The button’s ID is 555, and if the button is clicked, the getInfo message 
is sent to the dialog object. The button is created without the tabstop style. If the user navigates the 
dialog using the keyboard, the tab key will skip over the button. 


MyDialog^addButton(555, 100, 80, 40, 15, "&Get new Info", , 
"getInfo", "NOTAB") 


7.9.1.3. addBitmapButton 


»»-addBitmapButton(--id-,-x-,-y--*------*-4------4-4--------4--4-----------t-,-normal--» 
+-,-cx-+ +-,-cy-+ +-,-text-+ +-,-msgName-+ 


>--+------------ +--+------------- +--+------------- +--+---------- +--------------------- >< 


+-,-focused--+ +-,-selected--+ +-,-disabled--+ +-,-style--+ 


The addBitmapButton method adds a push button with a bitmap (instead of plain text) to the dialog. You 
can provide four different bitmaps representing the four states of a button. The bitmap push button is an 
owner-drawn button, where ooDialog internally handles the drawing of the button. 


Note: On Windows XP and later, using an image list with the button will produce a better overall 
appearance in the dialog. Using an image list gives the button the same look and feel as other 
buttons on the system. The buttons produced using this method and the connectBitmapButton() 
have the look and feel of Windows 98 buttons. When an image list is used with a button, the other 
button styles, such as the NOTIFY style can still be used. Whereas with the bitmap button the other 
button styles can not be used. The image list button supports all the features of the bitmap button, 
and more. 


The bitmaps can be specified by either a file name or a bitmap handle. You can retrieve a bitmap handle 
by loading a bitmap stored in a file into memory, using the method LoadBitmap). If you pass a bitmap 
handle to the method, you must use the INMEMORY option. 
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Arguments: 


The arguments are: 


id 
The resource ID for the control. 


X, у, CX, су 


The control coordinates 


text 


The text label for the button. Although the user will not see this text, (they see the bitmap 
instead,) the text is still associated with the button and can be retrieved by the programmer 
using the Title method of the DialogControl class. 

msgToRaise 


The name of a method of the dialog class that is to be invoked each time the button is clicked. 


bmpNormal 


A bitmap that is displayed when the button is in the normal state. I.e., it is not focused, not 
selected, and not disabled. This argument must be specified. If any of the other three bitmap 
arguments are omitted, this bitmap will be used in its place. 


focused 


A bitmap that is displayed if the button is focused. When a button is focused it receives the 
keyboard input and can be clicked by using the Enter or Space keys. Normally the focused 
button is surrounded by a dashed frame. If this argument is omitted, the normal bitmap is 
displayed for the focused state. 


selected 
A bitmap that is displayed while the button is clicked and held down. If this argument is 
omitted, the normal bitmap is displayed for the selected state. 

disabled 
A bitmap that is displayed if the button is disabled. If this argument is omitted, the normal 


bitmap is displayed for the disabled state. 


style 


Note: The 3.2.0 ooDialog documentation incorrectly stated you could use the NOTIFY style 
keyword. Do not do this. Owner-drawn buttons should not use any other button styles than 
owner-drawn. The result of using the NOTIFY style will be less than satisfactory. An image 
list button allows the use of the NOTIFY style and will give a better overall look to the 
dialog. Using an image list button should be the preferred method for non-text buttons 
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The last argument can be 0 or more of the following keywords: 


DEFAULT STRETCH | GROUP 
FRAME HIDDEN TAP 
USEPAL DISABLED NOTAB 
INMEMORY BORDER 


DEFAULT 


The button becomes the default button in the dialog. 


FRAME 


The button is drawn with a 3D frame. Internally, ooDialog draws the button. However, the 
technique used is now out of date. This gives your bitmap the same appearance as buttons 
in Windows 98. To have your buttons match the Window XP and Vista styles use an 
image list with the button as described in the opening comments above. 


USEPAL 


The color palette of the bitmap is loaded and used. This argument should be specified for 
just one of the dialog buttons, because only one color palette can be active at any time. 


INMEMORY 


Specifies that the bitmap is already loaded into memory. If you switch often between 
different bitmaps within one button, the loading of all bitmaps into memory increases 
performance. 


STRETCH 


If this option is specified and the extent of the bitmap is smaller than the extent of the 
button rectangle, the bitmap is adapted to match the extent of the button. 


HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 


BORDER 


The border window style. 


GROUP 
The group control style. 


NOTAB 


The no tabstop control style. By default the button is created with the tabstop style except 
in these conditions: the bmpFocused is omitted, and the bmpSelected is omitted, and the 
FRAME style keyword is not used. 
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TAB 


The tabstop control style. The button is normally created with the tabstop style and this 
keyword is not necessary. However, if the bmpFocused argument is omitted, and the 
bmpSelected argument is omitted, and the FRAME style keyword is not used, the button 
is created without the tabstop style. In this case only, it is necessary to use the TAB 
keyword to change the default behavior. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


The following example defines a button with ID 601. The bitmap in the Button1. bmp file is 
displayed for the push button instead of a black text on a grey background. If the button is disabled 
(by using the DisableItem method, see page DisableItem), the bitmap is exchanged and 
Button1D.bmp is shown instead. If the button is clicked, the BmpPushed message is sent. 


MyDialog^addBitmapButton(601, 20, 317, 80, 30, , "BmpPushed", , 
"Buttoni.bmp", , ,"ButtoniD.bmp","FRAME USEPAL") 


7.9.1.4. addButtonGroup 


»»-addButtonGroup(-x-,-y-*------*-*------4-,--txt- -id- -msg-*--*-------*-4--------4*-)-»« 
+-,-сх-+ +-,-су-+ +-,-row-+ +-,-opts-+ 


Use the addButtonGroup method to add more than one push button at once to the dialog. The buttons are 
arranged in a row or in a column. 


Arguments: 


The arguments are: 


X, у, CX, cy 


The control coordinates. In this case x and y are the position of the entire group. cx and cy are 
the size of a single button and both are optional. The default for cx is 40 and for cy 12. 
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txt ID msg 


TOW 


opts 


These arguments are interpreted as one string containing three words (separated by blanks) for 
each button. The first word is the text that is displayed on the button. The second is the 
resource ID of the button, and the third is the name of a message that is sent to the object 
whenever the button is clicked. The fourth to sixth words are for the next button, and so forth. 


This is a flag to switch between horizontal or vertical placement of the buttons. If row is true, 
the buttons are placed horizontal, if row is false the buttons are placed vertically. 


A list of 0 or more of the following style keywords separated by spaces. Each button is given 
the same set of styles, except for the DEFAULT style. This is only given to the first button: 


DEFAULT HCENTER FLAT 


OWNER TOP HIDDEN 
BITMAP BOTTOM DISABLED 
ICON VCENTER BORDER 
LEFT MULTILINE GROUP 


RIGHT NOTIFY NOTAB 


DEFAULT 


The button becomes the default button in the dialog. 


OWNER 


The programmer is completely responsible for drawing the button when the dialog 
receives the WM_DRAWITEM message. Currently this would be difficult (but not 
impossible) to implement in ooDialog. A simpler approach for an owner drawn button is 
to use a bitmap button. See the addBitmapButton method. 


ICON 


The button displays an icon image. 


BITMAP 


The button displays a bitmap image. 


LEFT 


Left justifies the text in the button rectangle. If neither LEFT nor RIGHT are specified the 
text is centered in the button rectangle. 


RIGHT 


Right justifies the text in the button rectangle. If neither LEFT nor RIGHT are specified 
the text is centered in the button rectangle. 


HCENTER 


The button has its text centered horizontally in the button rectangle. This is the default if 
neither LEFT nor RIGHT are specified. 
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TOP 


The text is aligned at the top of the button rectangle. If neither TOP nor BOTTOM are 
specified the text is vertically centered in the button rectangle. 


BOTTOM 


The text is aligned at the bottom of the button rectangle. If neither TOP nor BOTTOM are 
specified the text is vertically centered in the button rectangle. 


VCENTER 


The text is vertically centered in the button rectanble. This is the default if neither TOP 
nor BOTTOM are specified. 


MULTILINE 


If the text for the label of the button is longer than the width of the button rectangle, the 
operating system will word wrap the text producing more than one line. The height of the 
button rectangle has to be sufficient to display the extra line(s) or the text is clipped. 


NOTIFY 


Enables the button to send notifications for the gained focus, lost focus, and double click 
events. This is only necessary when the connectButtonNotify method is used, and only for 
the GOTFOCUS, LOSTFOCUS, or DBLCLK keywords of that method. Note that only 
radio buttons and owner-drawn buttons will recieve the DBLCLK event. 


FLAT 


The button is drawn with a flat appearance, i.e., it is drawn as a flat rectangle the label text 
inside the rectangle. 


HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 


BORDER 


The border window style. 


GROUP 
The group control style. 


NOTAB 


The no tabstop control style. 
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Return value: 


The possible return values are: 


Success. 
less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 
The following example creates three buttons (Add, Delete, and Update): 


MyDialog^addButtonGroup(20, 235, , , = 
"¥Add 301 AddItem " = 
"&Delete 302 DeleteItem " - 
"&Update 303 UpdateItem") 


7.9.1.5. addOkCancelRightBottom 


>>--add0kCancelRightBottom----------------------- >< 


The addOkCancelRightBottom method adds an OK and a Cancel push button horizontally to the 
lower-right edge of the dialog. 


Return value: 


The possible return values are: 


Success. 
less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


The following example adds the push buttons to the bottom of the dialog. It also overrides the 
standard OK and Cancel methods. 


::class MyClass subclass UserDialog 


::method DefineDialog 


self^addOkCancelRightBottom 


::method OK 
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ret = MessageBox("Are you sure?", "Please confirm", "OK") 
if ret-1 then self~OK:super 


::method Cancel 


ret = MessageBox("Do you really want to quit?", "Please confirm", "OK") 
if ret-1 then self^CANCEL:super 


7.9.1.6. addOkCancelLeftBottom 


»»--addOkCancelLeftBottom------------------------ >< 


The addOkCancelLeftBottom method adds an ОК and a Cancel push button horizontally to the 
lower-left edge of the dialog. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


7.9.1.7. addOkCancelRightTop 


»»--addÜükCancelRightTop-------------------------- >< 


The addOkCancelRightTop method adds an ОК and a Cancel push button vertically to the upper-right 
edge of the dialog. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 
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7.9.1.8. addOkCancelLeftTop 


»»--addOÜkCancelLeftTop--------------------------- >< 


The addOkCancelLeftTop method adds an ОК апа a Cancel push button vertically to the upper-left edge 
of the dialog. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


7.9.1.9. addRadioButton 


>>--addRadioButton (-14-+--------+-,-х-,-у--+------+--+------+-,-бех-+--------- +-)-->< 


+- ,-паше-+ е ск tcy t +-,-style-+ 


The addRadioButton method adds a radio button to the dialog. The radio button is created as an 
automatic radio button. There is no way using this method to create a standard radio button. See the 
RadioButton class for more information on radio buttons. 


Arguments: 


The arguments are: 
id 
The resource ID for the control. 


name 


The name of the data attribute associated with the dialog item. Using this argument performs 
the same function as the connectRadioButton() method. The connectEntryLine() 
documentation has a good description of the concept of the data attribute. 


If you omitt this argument then the data attribute is constructed automatically and named by 
concatenating the string DATA with the id argument, 1.е.: DATA || id. 


X, y, CX, cy 


The control coordinates. If either cx or cy are omitted, then the size for the radio button is 
calculated internally using its label. (The text argument.) 
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text 


The text that is displayed next to the radio button 


style 


A list of 0 or more of the following style keywords separated by spaces: 


OWNER TOP FLAT 
BITMAP BOTTOM HIDDEN 
ICON VCENTER DISABLED 
LEFT MULTILINE BORDER 


RIGHT NOTIFY GROUP 
HCENTER PUSHLIKE NOTAB 


OWNER 


The programmer is completely responsible for drawing the button when the dialog 
receives the WM_DRAWITEM message. Currently this would be difficult (but not 
impossible) to implement in ooDialog. For a radio button, the difficulty would probably 
make this impractical. 


ICON 


The button displays an icon image. 


BITMAP 


The button displays a bitmap image. 


LEFT 


Left justifies the text to the right of the radio button. 


RIGHT 


Right justifies the text to the right side of the radio button. 


HCENTER 


The text is centered horizontally to the right of the radio button. This is the default if 
neither LEFT nor RIGHT are specified. 


TOP 


The text is aligned at the top of the button rectangle. If neither TOP nor BOTTOM are 
specified the text is vertically centered in the button rectangle. 


BOTTOM 


The text is aligned at the bottom of the button rectangle. If neither TOP nor BOTTOM are 
specified the text is vertically centered in the button rectangle. 


VCENTER 


The text is vertically centered in the button rectanble. This is the default if neither TOP 
nor BOTTOM are specified. 
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MULTILINE 


If the text for the label of the button is longer than the width of the button rectangle, the 
operating system will word wrap the text producing more than one line. The height of the 
button rectangle has to be sufficient to display the extra line(s) or the text is clipped. 


NOTIFY 


Enables the button to send notifications for the gained focus, lost focus, and double click 
events. This is only necessary when the connectButtonNotify method is used, and only for 
the GOTFOCUS, LOSTFOCUS, or DBLCLK keywords of that method. Note that only 
radio buttons and owner-drawn buttons will recieve the DBLCLICK event. 


PUSHLIKE 


Makes the button look and act like a push button. The button looks raised when it isn’t 
pushed or checked, and sunken when it is pushed or checked. The button is drawn with a 
flat appearance, i.e., it is drawn as a flat rectangle the label text inside the rectangle. 


FLAT 


The button is drawn with a flat appearance, i.e., it is drawn as a flat rectangle the label text 
inside the rectangle. 


HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 


BORDER 


The border window style. 


GROUP 


The group control style. For the auto radio buttons to work, the first radio button should 
be given the group style. None of the other radio buttons should have the group style. The 
first control that has the group style then ends the group. 


NOTAB 


The no tabstop control style. 


Return value: 


The possible return values are: 


Success. 
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less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 
The following example defines seven radio buttons with IDs 501 through 507: 


RText .1="Monday" 
RText .2="Tuesday" 
RText .3="Wednesday" 
RText .4="Thursday" 
RText .5="Friday" 
RText .6="Saturday" 
RText.7-"Sunday" 


do i21 to 7 
MyDialog^addRadioButton(500*i, , 20, 1#15+13, 40, 14, RText.i) 
end 


Note: There are also methods that create a whole group automatically (see the addRadioGroup 
method below and addRadioStem). 


7.9.1.10. addRadioGroup 


V | 
»»--addRadioGroup(id1,-x-,-y-*------*-,---text-t--*--------- +---------- +-)--->< 
+=,=сх=+ +-,-style-+-,-idStat-+ 


Creates a complete group of auto radiobuttons. 


Arguments: 


The arguments are: 


141 
The resource ID for Ше first radio button. This id is increased by 1 for each additional radio 
button and then assigned to the control. 

X, y, CX 


The control coordinates. x and y name the position of the first radio button control. The other 
radio buttons are positioned automatically. cx specifies the length of the radio button plus text. 
If omitted, the space needed is calculated. 
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text 


The text string for each radio button. Single words have to be separated by blank spaces. This 
argument determines the number of radio buttons in total. Note that this prevents using more 
than one word for the label of any radio button. 


style 


A list of 0 or more of the following style keywords separated by spaces. Each radio button in 
the group is given the style specified by this option. 


OWNER TOP FLAT 
BITMAP BOTTOM HIDDEN 
ICON VCENTER DISABLED 
LEFT MULTILINE NOBORDER 


RIGHT NOTIFY GROUP 
HCENTER PUSHLIKE NOTAB 


OWNER 


The programmer is completely responsible for drawing the button when the dialog 
receives the WM_DRAWITEM message. Currently this would be difficult (but not 
impossible) to implement in ooDialog. For a radio button, the difficulty would probably 
make this impractical. 


ICON 


The button displays an icon image. 


BITMAP 


The button displays a bitmap image. 


LEFT 


Left justifies the text to the right of the radio button. 


RIGHT 


Right justifies the text to the right side of the radio button. 


HCENTER 


The text is centered horizontally to the right of the radio button. This is the default if 
neither LEFT nor RIGHT are specified. 


TOP 


The text is aligned at the top of the button rectangle. If neither TOP nor BOTTOM are 
specified the text is vertically centered in the button rectangle. 


BOTTOM 


The text is aligned at the bottom of the button rectangle. If neither TOP nor BOTTOM are 
specified the text is vertically centered in the button rectangle. 
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VCENTER 


The text is vertically centered in the button rectanble. This is the default if neither TOP 
nor BOTTOM are specified. 


MULTILINE 


If the text for the label of the button is longer than the width of the button rectangle, the 
operating system will word wrap the text producing more than one line. The height of the 
button rectangle has to be sufficient to display the extra line(s) or the text is clipped. 


NOTIFY 


Enables the button to send notifications for the gained focus, lost focus, and double click 
events. This is only necessary when the connectButtonNotify method is used, and only for 
the GOTFOCUS, LOSTFOCUS, or DBLCLK keywords of that method. Note that only 
radio buttons and owner-drawn buttons will recieve the DBLCLICK event. 


PUSHLIKE 


Makes the button look and act like a push button. The button looks raised when it isn’t 
pushed or checked, and sunken when it is pushed or checked. The button is drawn with a 
flat appearance, i.e., it is drawn as a flat rectangle the label text inside the rectangle. 


FLAT 


The button is drawn with a flat appearance, i.e., it is drawn as a flat rectangle the label text 
inside the rectangle. 


HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 


NOBORDER 


Use this keyword to specify that a group box is not added around the radio button group. 


GROUP 


Do not use this keyword with this method. The group style is added correctly internally. 


NOTAB 


The no tabstop control style. 


idstat 


This argument is used to set the resource ID for the group box, if one is used. The argument is 
ignored if the NOBORDER style is used. 
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Example: 


The following example adds a group of three radio buttons with IDs 301, 302, and 303 to the dialog 
(see Sample Radio Button Group): 

MyDialog = .UserDialog^new 

MyDialog^Create(100,100,80,60,"Radio Button Group") 

MyDialog^addRadioGroup(301, 23, 18, ,"Fast Medium Slow") 

MyDialog^ fast = 1 

MyDialog^ Execute 


Figure 7-1. Sample Radio Button Group 
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7.9.1.11. addRadioStem 


>>--addRadioStem(id1,-x-,-y-+------+-,-text.-,-max--+--------- *---------- +-)--->< 
+=,=су=+ +-,-style-+-,-idStat-+ 


The addRadioStem method adds a group of radio button controls to the dialog. It is very similar to the 
addRadioGroup() method. It simply uses a stem to specify the text label for each radio button. Notice 
that this will allow the labels to consist of more than one word, which removes the restriction of the 
addRadioGroup() method that labels must be a single word. 


Note: The documentation prior to version 4.0.0 listed a font name and a font size argument. These 
arguments do nothing and are ignored in ooDialog 4.0.0 and later. 


Arguments: 
The arguments are: 
141 


The resource ID for Ше first radio button. This id is increased Бу 1 for each additional radio 
button and then assigned to the control. 


302 ooRexx OODialog Reference Version 4.0.0 


Chapter 7. UserDialog Class 


X, y, CX 


The control coordinates. x and y name the position of the first radio button control. The other 
radio buttons are positioned automatically. cx specifies the length of the radio button plus text. 
If omitted, the space needed is calculated. 


text. 


A stem containing the text label for each radio button. The stem indexes shoud start at 1 and 
continue consecutively, with each succeding number containing the the label for the next 
radion button. This argument determines the number of radio buttons in total. 


A number specifying the maximum radio buttons to put in a column. The programmer can use 
this to balance the look of the group by placing the buttons in more than | column. For 
instance, if there are 8 radio buttons and the max argument is 4 then the result will have 4 radio 
buttons in 2 side-by-side columns. 


style 


A list of 0 or more of the following style keywords separated by spaces. Each radio button in 
the group is given the style specified by this option. 


OWNER TOP FLAT 
BITMAP BOTTOM HIDDEN 
ICON VCENTER DISABLED 
LEFT MULTILINE NOBORDER 


RIGHT NOTIFY GROUP 
HCENTER PUSHLIKE NOTAB 


OWNER 


The programmer is completely responsible for drawing the button when the dialog 
receives the WM. DRAWITEM message. Currently this would be difficult (but not 
impossible) to implement in ooDialog. For a radio button, the difficulty would probably 
make this impractical. 


ICON 


The button displays an icon image. 


BITMAP 


The button displays a bitmap image. 


LEFT 


Left justifies the text to the right of the radio button. 


RIGHT 


Right justifies the text to the right side of the radio button. 


HCENTER 


The text is centered horizontally to the right of the radio button. This is the default if 
neither LEFT nor RIGHT are specified. 
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TOP 


The text is aligned at the top of the button rectangle. If neither TOP nor BOTTOM are 
specified the text is vertically centered in the button rectangle. 


BOTTOM 


The text is aligned at the bottom of the button rectangle. If neither TOP nor BOTTOM are 
specified the text is vertically centered in the button rectangle. 


VCENTER 


The text is vertically centered in the button rectanble. This is the default if neither TOP 
nor BOTTOM are specified. 


MULTILINE 


If the text for the label of the button is longer than the width of the button rectangle, the 
operating system will word wrap the text producing more than one line. The height of the 
button rectangle has to be sufficient to display the extra line(s) or the text is clipped. 


NOTIFY 


Enables the button to send notifications for the gained focus, lost focus, and double click 
events. This is only necessary when the connectButtonNotify method is used, and only for 
the GOTFOCUS, LOSTFOCUS, or DBLCLK keywords of that method. Note that only 
radio buttons and owner-drawn buttons will recieve the DBLCLICK event. 


PUSHLIKE 


Makes the button look and act like a push button. The button looks raised when it isn’t 
pushed or checked, and sunken when it is pushed or checked. The button is drawn with a 
flat appearance, i.e., itis drawn as a flat rectangle the label text inside the rectangle. 


FLAT 


The button is drawn with a flat appearance, i.e., it is drawn as a flat rectangle the label text 
inside the rectangle. 


HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 


NOBORDER 


Use this keyword to specify that a group box is not added around the radio button group. 


GROUP 


Do not use this keyword with this method. The group style is added correctly internally. 


NOTAB 


The no tabstop control style. 
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idstat 


This argument is used to set the resource ID for the group box, if one is used. The argument is 
ignored if the NOBORDER style is used. 


Example: 


The following example is complete. It can be cut and pasted into a file and run as is. It adds a group 
of four radio buttons with IDs 304, 305, 306, and 307, in a group with two buttons each in two 
columns. The group box for the group is give a resource ID of 300. In initDialog(), the group box is 
then given a label and the first radio button is checked. 


/* Simple test of add ... */ 
dlg = .SimpleRB “new 
if dlg~initCode = 0 then до 
dlg^createCenter(150, 83, "Testing Radio Buttons", "VISIBLE", , "Ms Shell Dlg 2", 8) 
dlg^Execute("SHOWTOP") 
dlg^Deinstall 
end 
::requires "oodWin32.cls" 


::class ’SimpleRB’ subclass UserDialog inherit AdvancedControls 


::method defineDialog 


labels.1 = ’Upper class’ 
labels.2 = ’Middle class’ 
labels.3 = ’Business class’ 
labels.4 = "Lower class? 


self~addRadioStem(304, 10, 13, ,labels., 2, "LEFTTEXT", 300) 


self~addButton(IDOK, 10, 60, 50, 14, "OK", ok, "DEFAULT GROUP") 
self~addButton(IDCANCEL, 65, 60, 50, 14, "Cancel", cancel) 


::method initDialog 
self^getGroupBox(300)^setTitle("Class Warfare") 
self~getRadioControl (304) ~check 





7.9.1.12. addCheckBox 
>>--ааабһескВох(-14--+--------+-,-х-,-у--+------+--+------+-,-фех--+--------- +-)-->< 
+-,-паше-+ +=, ех + t= Eyk +-,-style-+ 


The addCheckBox() method adds a check box to the dialog. By default the check box will be an 
automatic check box. This can be changed to an automatic three-state check box by using the 3STATE 
style. Standard and standard three-state check boxes can not be created through this method. See the 
CheckBox class for more information on check box controls. 
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Arguments: 


The arguments are: 


id 
The resource ID for the control. 

name 
The name of the data attribute associated with the dialog item. Using this argument performs 
the same function as the connectCheckBox() method. The connectEntryLine() documentation 
has a good description of the concept of the data attribute. 
If you omitt this argument then the data attribute is constructed automatically and named by 
concatenating the string DATA with the id argument, 1.е.: DATA || 14. 

X, у, CX, су 
The control coordinates If cx or cy are omitted, then the size for the check box is calcuated 
internally using its label. (The text argument.) 

text 
The text that is displayed next to the check box. 

style 


A list of 0 or more of the following style keywords separated by spaces: 


3STATE TOP HIDDEN 
OWNER BOTTOM DISABLED 
BITMAP VCENTER BORDER 
ICON MULTILINE GROUP 
LEFT NOTIFY NOTAB 
RIGHT PUSHLIKE 

HCENTER FLAT 


3STATE 
A three-state check box is created. All check box controls have two states, checked and 
cleared (not checked.) A three-state check box also has an indeterminate state. This is 
represented by a grayed box inside the check box. The programmer can use methods of 
the CheckBox class to determine which of the 3 states a check box is in. 


OWNER 


The programmer is completely responsible for drawing the button when the dialog 
receives the WM_DRAWITEM message. Currently this would be difficult (but not 
impossible) to implement in ooDialog. For a check box, the difficulty would probably 
make this impractical. 


ICON 


The check box displays an icon image. 


BITMAP 
The check box displays a bitmap image. 
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LEFT 


Left justifies the text to the right of the check box. 


RIGHT 
Right justifies the text to the right side of the check box. 


HCENTER 
The text is centered horizontally to the right of the check box. This is the default if neither 
LEFT nor RIGHT are specified. 

TOP 
The text is aligned at the top of the button rectangle. If neither TOP nor BOTTOM are 
specified the text is vertically centered in the button rectangle. 

BOTTOM 
The text is aligned at the bottom of the button rectangle. If neither TOP nor BOTTOM are 
specified the text is vertically centered in the button rectangle. 

VCENTER 
The text is vertically centered in the button rectanble. This is the default if neither TOP 
nor BOTTOM are specified. 

MULTILINE 
If the text for the label of the button is longer than the width of the button rectangle, the 
operating system will word wrap the text producing more than one line. The height of the 
button rectangle has to be sufficient to display the extra line(s) or the text is clipped. 


NOTIFY 


Enables the button to send notifications for the gained focus,lost focus, and double click 
events. This is only necessary when the connectButtonNotify method is used, and only for 
the GOTFOCUS, LOSTFOCUS, or DBLCLK keywords of that method. Note that only 
radio buttons and owner-drawn buttons will recieve the DBLCLICK event. 


PUSHLIKE 


Makes the button look and act like a push button. The button looks raised when it isn’t 
pushed or checked, and sunken when it is pushed or checked. The button is drawn with a 
flat appearance, i.e., itis drawn as a flat rectangle the label text inside the rectangle. 


FLAT 


The button is drawn with a flat appearance, i.e., it is drawn as a flat rectangle the label text 
inside the rectangle. 


HIDDEN 


The not visible window style. 
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DISABLED 


The not enabled window style. 


BORDER 


The border window style. 


GROUP 
The group control style. 


NOTAB 


The no tabstop control style. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


The following example defines an automatic three-state check box. The label for the check box is 
rather long, so a multiline style is used. 


::method defineDialog 
label = "Use condensed type only" 


style = "3STATE MULTILINE NOTIFY" 
self~addCheckBox(IDC_CB_CONDENSED, , 125, 19, 30, 20, label, style) 


Note: There are also methods that create a whole group of check boxes automatically (see the 
addCheckGroup method below and addCheckBoxStem). 


7.9.1.13. addCheckGroup 


ү | 
»»--addCheckGroup(id1,-x-,-y-*------4-,---text-t--*--------- +---------- +-)--->< 
+- <сх-+ +-,-style-+-,-idStat-+ 
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The addCheckGroup method creates a group of check boxes. This method believes the same as the 
addRadioGroup() method. 


Arguments: 


The arguments are: 


141 
The resource ID for Ше first check box. This id is increased by 1 for each additional check box 
and then assigned to the control. 


X, y, CX 
The control coordinates. x and y name the position of the first check box control. The other 
check boxes are positioned automatically. cx specifies the length of the check box plus text. If 
omitted, the space needed is calculated. 


text 


The text string for each check box. Single words have to be separated by blank spaces. This 
argument determines the number of check boxes in total. Note that this prevents using more 
than one word for the label of any check box. 


style 
A list of 0 or more of the following style keywords separated by spaces. Each check box in the 
group is given the style specified by this option. 
3STATE TOP HIDDEN 
OWNER BOTTOM DISABLED 
BITMAP VCENTER | NOBORDER 
ICON MULTILINE GROUP 
LEFT NOTIFY NOTAB 


RIGHT PUSHLIKE 
HCENTER FLAT 


3STATE 


A three-state check box is created. All check box controls have two states, checked and 
cleared (not checked.) A three-state check box also has an indeterminate state. This is 
represented by a grayed box inside the check box. The programmer can use methods of 
the CheckBox class to determine which of the 3 states a check box is in. 


OWNER 
The programmer is completely responsible for drawing the button when the dialog 
receives the WM_DRAWITEM message. Currently this would be difficult (but not 
impossible) to implement in ooDialog. For a check box, the difficulty would probably 
make this impractical. 


ICON 


The button displays an icon image. 
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BITMAP 


The button displays a bitmap image. 


LEFT 


Left justifies the text to the right of the check box. 


RIGHT 
Right justifies the text to the right side of the check box. 


HCENTER 
The text is centered horizontally to the right of the check box. This is the default if neither 
LEFT nor RIGHT are specified. 

TOP 
The text is aligned at the top of the button rectangle. If neither TOP nor BOTTOM are 
specified the text is vertically centered in the button rectangle. 

BOTTOM 
The text is aligned at the bottom of the button rectangle. If neither TOP nor BOTTOM are 
specified the text is vertically centered in the button rectangle. 

VCENTER 
The text is vertically centered in the button rectanble. This is the default if neither TOP 
nor BOTTOM are specified. 

MULTILINE 


If the text for the label of the button is longer than the width of the button rectangle, the 
operating system will word wrap the text producing more than one line. The height of the 
button rectangle has to be sufficient to display the extra line(s) or the text is clipped. 


NOTIFY 


Enables the button to send notifications for the gained focus,lost focus, and double click 
events. This is only necessary when the connectButtonNotify method is used, and only for 
the GOTFOCUS, LOSTFOCUS, or DBLCLK keywords of that method. Note that only 
radio buttons and owner-drawn buttons will recieve the DBLCLICK event. 


PUSHLIKE 


Makes the button look and act like a push button. The button looks raised when it isn’t 
pushed or checked, and sunken when it is pushed or checked. The button is drawn with a 
flat appearance, i.e., it is drawn as a flat rectangle the label text inside the rectangle. 


FLAT 


The button is drawn with a flat appearance, i.e., it is drawn as a flat rectangle the label text 
inside the rectangle. 
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HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 


NOBORDER 


Use this keyword to specify that a group box is not added around the check box group. 


GROUP 
Do not use this keyword with this method. The group style is added correctly internally. 


NOTAB 


The no tabstop control style. 


idstat 


This argument is used to set the resource ID for the group box, if one is used. The argument is 
ignored if the NOBORDER style is used. 


Example: 


The following example adds a group of four check boxes to the dialog. Two check boxes are 
preselected (see Sample Check Box Group): 


MyDialog^addCheckGroup(401, 23, 18, ,"Smalltalk C++ ObjectRexx 00-СОВОГ.") 
MyDialog^smalltalk = 1 
MyDialog^objectrexx - 1 


Figure 7-2. Sample Check Box Group 
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7.9.1.14. addCheckBoxStem 


»»--addCheckBoxStem(id1,-x-,-y-*------*-,-text.-,-max--*--------- +---------- +-)--->< 
+-,-cx-+ +-,-style-+-,-idStat-+ 
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The addCheckBoxStem method creates a group of check box controls. Unlike the addCheckGroup 
method you pass the titles of the check boxes in a stem variable instead of using a string. Therefore you 


can use labels that include blanks. This method is similar to the addRadioStem() method, but for check 
boxes. 


Note: The documentation prior to version 4.0.0 listed a font name and a font size argument. These 
arguments do nothing and are ignored in ooDialog 4.0.0 and later. 


Arguments: 


The arguments are: 


141 


The resource ID for Ше first check box This id is increased Бу 1 for each additional check box 
and then assigned to the control. 


X, y, CX 


The control coordinates. x and y name the position of the first check box control. The other 
check boxes are positioned automatically. cx specifies the length of the check plus text. If 
omitted, the space needed is calculated. 


text. 


A stem containing the text label for each check box. The stem indexes shoud start at 1 and 
continue consecutively, with each succeding number containing the the label for the next check 
box. This argument determines the number of check boxes in total. 


A number specifying the maximum check boxes to put in a column. The programmer can use 
this to balance the look of the group by placing the check boxe in more than 1 column. For 
instance, if there are 8 check boxes and the max argument is 4 then the result will have 4 check 
boxes in 2 side-by-side columns. Likewise if max is 3 and there are 9 check boxes, then this 
methods will create 3 columns of 3 check boxes. 


style 


A list of 0 or more of the following style keywords separated by spaces. Each check box in the 
group is given the style specified by this option. 


3STATE TOP HIDDEN 
OWNER BOTTOM DISABLED 
BITMAP VCENTER | NOBORDER 
ICON MULTILINE GROUP 
LEFT NOTIFY NOTAB 
RIGHT PUSHLIKE 

HCENTER FLAT 


3STATE 


A three-state check box is created. All check box controls have two states, checked and 
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cleared (not checked.) A three-state check box also has an indeterminate state. This is 
represented by a grayed box inside the check box. The programmer can use methods of 
the CheckBox class to determine which of the 3 states a check box is in. 


OWNER 


The programmer is completely responsible for drawing the button when the dialog 
receives the WM_DRAWITEM message. Currently this would be difficult (but not 
impossible) to implement in ooDialog. For a check box, the difficulty would probably 
make this impractical. 


ICON 


The button displays an icon image. 


BITMAP 


The button displays a bitmap image. 


LEFT 


Left justifies the text to the right of the check box. 


RIGHT 
Right justifies the text to the right side of the check box. 


HCENTER 
The text is centered horizontally to the right of the check box. This is the default if neither 
LEFT nor RIGHT are specified. 

TOP 
The text is aligned at the top of the button rectangle. If neither TOP nor BOTTOM are 
specified the text is vertically centered in the button rectangle. 

BOTTOM 
The text is aligned at the bottom of the button rectangle. If neither TOP nor BOTTOM are 
specified the text is vertically centered in the button rectangle. 

VCENTER 
The text is vertically centered in the button rectanble. This is the default if neither TOP 
nor BOTTOM are specified. 

MULTILINE 


If the text for the label of the button is longer than the width of the button rectangle, the 
operating system will word wrap the text producing more than one line. The height of the 
button rectangle has to be sufficient to display the extra line(s) or the text is clipped. 


NOTIFY 


Enables the button to send notifications for the gained focus, lost focus, and double click 
events. This is only necessary when the connectButtonNotify method is used, and only for 
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the GOTFOCUS, LOSTFOCUS, or DBLCLK keywords of that method. Note that only 
radio buttons and owner-drawn buttons will recieve the DBLCLICK event. 
PUSHLIKE 


Makes the button look and act like a push button. The button looks raised when it isn’t 
pushed or checked, and sunken when it is pushed or checked. The button is drawn with a 
flat appearance, i.e., it is drawn as a flat rectangle the label text inside the rectangle. 


FLAT 


The button is drawn with a flat appearance, i.e., it is drawn as a flat rectangle the label text 
inside the rectangle. 


HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 


NOBORDER 


Use this keyword to specify that a group box is not added around the check box group. 


GROUP 


Do not use this keyword with this method. The group style is added correctly internally. 


NOTAB 


The no tabstop control style. 


idstat 


This argument is used to set the resource ID for the group box, if one is used. The argument is 
ignored if the NOBORDER style is used. 


Example: 


The following example is complete. It can be cut and pasted into a file and run as is. It adds a group 
of six check boxes with consecutive IDs of 304 through 309. They are placed in a group with two 
check boxes each in three columns. The group box for the group is give a resource ID of 300. In 
initDialog(), the group box is then given a label and the first and fifth check boxes are checked. 


/* Simple test of add ... */ 
dlg = .SimpleCB^new 


if dlg~initCode = 0 then до 
dlg^createCenter(215, 83, "Testing Check Boxes", "VISIBLE", , "Ms Shell Dlg 2", 8) 
dlg^Execute("SHOWTOP") 
dlg^Deinstall 

end 
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::requires "oodWin32.cls" 
::class ’SimpleCB’ subclass UserDialog inherit AdvancedControls 


::method defineDialog 


labels.1 = ’Upper class’ 
labels.2 = ’Middle class’ 
labels.3 = ’Business class’ 
labels.4 = ’Lower class’ 
labels.5 = ’Classless’ 


labels.6 = ’Class clown’ 
self~addCheckBoxStem(304, 10, 13, ,labels., 2, "LEFTTEXT RIGHT", 300) 


self~addButton(IDOK, 10, 60, 50, 14, "OK", ok, "DEFAULT GROUP") 
self~addButton(IDCANCEL, 65, 60, 50, 14, "Cancel", cancel) 


::method initDialog 
self^getGroupBox(300)^style = "LEFT" 
self^getGroupBox(300)^setTitle("Class Warfare") 
self~getCheckControl (304) ~check 
self~getCheckControl (308) ~check 





::method initAutoDetection 
self^noAutoDetection 


7.9.2. Add Static Controls 


The methods in this section are all used to add a static control to the dialog. However, there is no need to 
use a number of different methods to add static controls. The addStatic method is all that is needed. You 
control the appearance and behavior of the static control in the same way as with other controls, by 
specifying the appropriate control styles. Given the proper combination of style keywords, the addStatic 
method can create any static control that the other methods in this section create. 


However, there are a large number of style keywords for the static control. Many of the keywords have 
no meaning when used in combination with other keywords. For instance, the ENDELLIPIS keyword 
has no meaning if used with the ICON keyword. The other methods in this section are convenience 
methods where the number of style keywords are reduced to only those that make sense in combination. 


A word about frames and rectangles. In previous versions of the ooDialog reference frames and 
rectangles were documented as though they were a type of separate controls. They are not, they are just a 
static control with a particular style. The Frames and Rectangles picture gives some idea of how the 
different types of static controls can appear. 
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Figure 7-3. Frames and Rectangles 
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7.9.2.1. addStatic 


»»-dlg^addStatic(-—*---—*--,-x-,-y-,-cx-,-cy------------ +--+--------- +--)---->< 
+-id-+ +-,-style--+--+- ,-text--+ 


The addStatic method adds any type of static control. The 3 basic types of static controls are static text, 
static image, and static frames / rectangles. 


Arguments: 


The resource ID for the static control. 


X, y, CX, Cy 


The control coordinates 


style 


A list of 0 or more style keywords separated by spaces. The keywords: TEXT, BITMAP, 
METAFILE, ICON, WHITERECT, GRAYRECT, BLACKRECT, WHITEFRAME, 
GRAYFRAME, BLACKFRAME, ETCHED, HORZ, and VERT determine the type of static 
control to be created. If more than one of these type keywords is specified, which static control 
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is created is undefined. The other style keywords modify the appearance or behavior of the 
static control. 


TEXT 


A static text control is created, this is the default if no other static type is specified. 


BITMAP 


A static image control is created that will use a bitmap. 


METAFILE 


A static image control that uses a metafile will be created. 


ICON 


A static image control that uses an icon will be created. Cursors are also icons. 


WHITERECT 


A rectanglerectangle filled with the current window background color, which is white in 
the default color scheme. 


WHITEFRAME 


A frame drawn with the same color as the window background, which is white in the 
default color scheme. 


GRAYRECT 


A rectanglerectangle filled with the current screen background color, which is gray in the 
default color scheme. 


GRAYFRAME 


A frame drawn with the same color as the current screen background, which is gray in the 
default color scheme. 


BLACKRECT 


A rectanglerectangle filled with the current window frame color, which is black in the 
default color scheme. 


BLACKFRAME 


A frame drawn with the same color as the current window frames, which is black in the 
default color scheme. 


ETCHED 


A frame drawn with an etched appearance. 


HORZ 


A frame drawn with an etched appearance, but only the top horizontal line of the frame is 
drawn. In other words, this is a single horizontal line, whose position and length are 
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determined by the position and width of the imaginary frame specified by the control 
coordinates. 
VERT 


A frame drawn with an etched appearance, but only the left vertical line of the frame is 
drawn. In other words, this is a single vertical line, whose position and length are 
determined by the position and height of the imaginary frame specified by the control 
coordinates. 


LEFT 


Left aligns text for static text controls. Lines are automatically word wrapped. Words 
longer than the width of the control are truncated. This is the default for static text 
controls and does not need to be specified. 


CENTER 


Uses centered text alignment for static text controls. Lines are automatically word 
wrapped. Words longer than the width of the control are truncated. If no text alignment 
style is specified, the text is left aligned. 

RIGHT 


Right aligns text for static text controls. Lines are automatically word wrapped. Words 
longer than the width of the control are truncated. If no text alignment style is specified, 
the text is left aligned. 

SIMPLE 


A single line of left-aligned text is in the rectangle defined by the control coordinates. The 
text line cannot be shortened or altered in any way. If the control is disabled, the text is 
not grayed. 

LEFTNOWRAP 
A single line of text, left-aligned. Tabs are expanded, but words are not wrapped. Text that 
extends past the end of a line is clipped. 


NOTIFY 


Causes the static control to send notification messages for the click, double click, 
disabled, and enabled events. A static control without this style does not send notification 
messages. See the connectStaticNotify() method of the .MessageExtensions class for 
further information. 


SUNKEN 


The control is drawn with a half-sunken border around it. 


EDITCONTROL 


The static control will act like a multi-line edit control when it displays text. This consists 
of calculating the average character width in the same manner as the edit control, and not 
displaying a partially visible last line. 
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ENDELLIPSIS 


If the end of the text does not fit in the rectangle, it is truncated and ellipses are added. If a 
word that is not at the end of the text goes beyond the limits of the rectangle, it is 
truncated without ellipses. 


NOPREFIX 


Any ampersand (&) characters in the control’s text are not interpreted as accelerator 
prefix characters. The text is displayed with the ampersand removed and the next 
character in the text underlined. 


PATHELLIPSIS 


If the text is toO big for the specified rectangle, characters in the middle of the text are 
replaced with ellipses so that the result fits in the rectangle. If the text contains backslash 
(\) characters, this style preserves as much as possible of the text after the last backslash. 


WORDELLIPSIS 


Any word that does not fit in the rectangle is truncated and ellipses are added. 


CENTERIMAGE 


Bitmaps are centered in the static control that contains it. The control is not resized, so 
that a bitmap too large for the control will be clipped. If the static control contains a single 
line of text, the text is centered vertically in the client area of the control. 


RIGHTJUST 


The lower right corner of the static control with the BITMAP or ICON style remains fixed 
when the control is resized. Only the top and left sides are adjusted to accommodate a 
new bitmap or icon. 


SIZECONTROL 


Adjusts the bitmap to fit the size of the static control. For example, changing the locale 
can change the system font, and thus controls might be resized. If a static control had a 
bitmap, the bitmap would no longer fit the control. This style bit dictates automatic 
redimensioning of bitmaps to fit their controls. 


If CENTERIMAGE is specified, the bitmap or icon is centered (and clipped if needed). If 
CENTERIMAGE is not specified, the bitmap or icon is stretched or shrunk. 


Note that the redimensioning in the two axes are independent, and the result may have a 
changed aspect ratio. 

SIZEIMAGE 
The actual resource width of the image is used. 


SIZEIMAGE is always used in conjunction with ICON. For icon images, the static 
control is resized accordingly, but the icon remains aligned to the originally specified left 
and top edges of the control. 


Note that if CENTERIMAGE is also specified, the icon is centered within the control’s 
space rectangle. 
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HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 


BORDER 


The border window style. 


GROUP 
The group control style. 


TAB 


The tabstop control style. 


text 


The text for the static control. If this argument is omitted then the empty string is used. 


Return value: 


The possible return values are: 


Success. 
less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 
This example adds a static image control and a static text control. 
::method defineDialog 
self~addStatic(IDC_BMP_PICTURE, 10, 10, 20, 17, "BITMAP REALSIZEIMAGE") 
self~addStatic(IDC_ST_DESCRIPTION, 14, 190, 176, 20, "TEXT LEFT", "Description") 


self~addButton(IDC_PB_NEXT, 10, 223, 50, 14, "Next", onNext) 
self~addButton(IDOK, 140, 223, 50, 14, "Ok", ok, "DEFAULT") 


7.9.2.2. addText 


+-,-"LEFT"-+ 
>>-аддТехъ(--х--,--у--+------ +--+------ +--+-------- +--+---------- +--+------- +--)-->< 
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The addText method adds a static text control to Ше dialog. 


Arguments: 


X, у, CX, су 
The control coordinates. When cx and cy are omitted, then width and height of the control are 
calculated automatically based on the width and height of the text string. 

text 


The text for the static control. If this argument is omitted then the empty string is used. 


style 


A list of 0 or more style keywords separated by spaces. If this argument is omitted LEFT is the 
default. 


LEFT 
Left aligns the text. Lines are automatically word wrapped. Words longer than the width 
of the control are truncated. This is the default if the style argument is omitted. 
CENTER 
Center aligns the text alignment. Lines are automatically word wrapped. Words longer 
than the width of the control are truncated. If no text alignment style is specified, the text 
is left aligned. 
RIGHT 
Right aligns the text. Lines are automatically word wrapped. Words longer than the width 
of the control are truncated. If no text alignment style is specified, the text is left aligned. 
SIMPLE 
A single line of left-aligned text is used. The text line cannot be shortened or altered in 
any way. If the control is disabled, the text is not grayed. 
LEFTNOWRAP 
A single line of text, left-aligned is used. Tabs are expanded, but words are not wrapped. 
Text that extends past the end of a line is clipped. 
NOTIFY 


Causes the static control to send notification messages for the click, double click, 
disabled, and enabled events. A static control without this style does not send notification 
messages. See the connectStaticNotify() method of the .MessageExtensions class for 
further information. 
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CENTERIMAGE 


The text is centered vertically in the client area of the control. 


SUNKEN 


The control is drawn with a half-sunken border around it. 


EDITCONTROL 


The static control will act like a multi-line edit control for the text it displays. This 
consists of calculating the average character width in the same manner as the edit control, 
and not displaying a partially visible last line. 


ENDELLIPSIS 


If the end of the text does not fit in the rectangle, it is truncated and ellipses are added. Ifa 
word that is not at the end of the text goes beyond the limits of the rectangle, it is 
truncated without ellipses. 


NOPREFIX 


Any ampersand (&) characters in the control’s text are not interpreted as accelerator 
prefix characters. The text is displayed with the ampersand removed and the next 
character in the text underlined. 


PATHELLIPSIS 


If the text is too big for the specified rectangle, characters in the middle of the text are 
replaced with ellipses so that the result fits in the rectangle. If the text contains backslash 
(\) characters, this style preserves as much as possible of the text after the last backslash. 


WORDELLIPSIS 


Any word that does not fit in the rectangle is truncated and ellipses are added. 


HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 


BORDER 


The border window style. 


GROUP 
The group control style. 


TAB 


The tabstop control style. 
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The resource ID for the static control. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


This example is similar to the one used to produce the picture of frames and rectangles. You can 
copy and paste it into 2 files and it should run as is. 


/* UserAllStyles.rex Simple Dialog to display static frames */ 


dlg = .SimpleDialog^new( , ’Al11Styles.h’) 
if dlg^initCode = 0 then do 


dlg^createCenter(269, 183, "Frames and Rectangles", "", , "MS Shell Dlg 2", 8) 
dlg^Execute("SHOWTOP", IDI_DLG_OOREXX) 
end 


dlg^Deinstall 


return 0 
-- End of entry point. 


::class SimpleDialog subclass UserDialog inherit AdvancedControls MessageExtensions 
::method defineDialog 


self^addText(56, 6, 20, 8, "White") 
self^addText(100, 6, 19, 8, "Gray") 
self^addText(143, 6, 19, 8, "Black") 


self^addText(9, 31, 33, 8, "Rectangle") 

self^addWhiteRect(56, 25, 25, 20, "NOTIFY", IDC. ST WHITERECT) 
self^addGrayRect(100, 25, 25, 20, IDC. ST GRAYRECT) 
self^addBlackRect(143, 25, 25, 20, ТОС ST BLACKRECT) 


self^addText(9, 64, 33, 8, "Frame") 

self^addWhiteFrame(56, 58, 25, 20, "NOTIFY", IDC. ST WHITEFRAME) 
self~addGrayFrame(100, 58, 25, 20, , IDC_ST_GRAYFRAME) 
self^addBlackFrame(143, 58, 25, 20, IDC ST BLACKFRAME) 
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self~addText(9, 94, 46, 8, "Sunken") 

self~addWhiteFrame(56, 88, 25, 20, "NOTIFY SUNKEN", IDC_ST_WHITEFRAME_SUNKEN) 
self~addGrayFrame(100, 88, 25, 20, "SUNKEN", IDC_ST_GRAYFRAME_SUNKEN) 
self~addBlackFrame(143, 88, 25, 20, "SUNKEN", IDC_ST_BLACKFRAME_SUNKEN) 


self~addText(9, 125, 46, 8, "Border") 

self~addWhiteFrame(56, 119, 25, 20, "NOTIFY BORDER", IDC_ST_WHITEFRAME_BORDER) 
self~addGrayFrame(100, 119, 25, 20, "BORDER", IDC_ST_GRAYFRAME_BORDER) 
self^addBlackFrame(143, 119, 25, 20, "BORDER", IDC ST BLACKFRAME BORDER) 


self^addText(9, 151, 33, 20,"Sunken / Border", "CENTER") 

self^addWhiteFrame(56, 151, 25, 20, "NOTIFY SUNKEN BORDER", IDC ST WHITEFRAME SUNKEN BORDER) 
self~addGrayFrame(100, 151, 25, 20, "SUNKEN BORDER", Т0С ST GRAYFRAME SUNKEN, BORDER) 
self^addBlackFrame(143, 151, 25, 20, "SUNKEN BORDER", IDC ST BLACKFRAME SUNKEN, BORDER) 


self^addText(193, 31, 23, 8, "Etched") 

self^addText(193, 59, 31, 17, "Etched Horizontal") 
self^addText(193, 89, 31, 17, "Etched Vertical") 
self^addEtchedFrame(234, 25, 25, 20, "NOTIFY", IDC ST ETCHED) 
self^addEtchedHorizontal(234, 58, 25, 20, "NOTIFY", IDC. ST HORZ) 
self^addEtchedVertical(234, 88, 25, 20, "NOTIFY", IDC ST VERT) 


self~addButton(IDOK, 210, 157, 50, 14, "Ok", ok, "DEFAULT") 


self~connectStaticNotify(IDC_ST_WHITERECT, "CLICK", onClick) 
self~connectStaticNotify(IDC_ST_WHITEFRAME, "CLICK", onClick) 
self~connectStaticNotify(IDC_ST_WHITEFRAME_SUNKEN, "CLICK", onClick) 
self~connectStaticNotify(IDC_ST_WHITEFRAME_BORDER, "CLICK", onClick) 
self~connectStaticNotify(IDC_ST_WHITEFRAME_SUNKEN_BORDER, "CLICK", onClick) 
self~connectStaticNotify(IDC_ST_ETCHED, "CLICK", onClick) 
self~connectStaticNotify(IDC_ST_HORZ, "CLICK", onClick) 
self~connectStaticNotify(IDC_ST_VERT, "CLICK", onClick) 


::method onClick 
say 'Got click on static with ID:? .DlgUtil^loWord(arg(1)) 


/* AllStyles.h */ 


#define IDD_DIALOG1 100 
#define IDC_ST_WHITERECT 215 
#define IDC_ST_GRAYRECT 1001 
#define IDC_ST_BLACKRECT 1002 
#define IDC_ST_ETCHED 1003 
#define IDC_ST_WHITEFRAME 1004 
#define IDC_ST_GRAYFRAME 1005 
#define IDC_ST_BLACKFRAME 1006 
#define IDC_ST_HORZ 1007 
#define IDC_ST_WHITEFRAME_SUNKEN 1008 
#define IDC_ST_GRAYFRAME_SUNKEN 1009 
#define IDC_ST_BLACKFRAME_SUNKEN 1010 
#define IDC_ST_VERT 1011 
#define IDC_ST_WHITEFRAME_BORDER 1012 
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#define IDC_ST_GRAYFRAME_BORDER 1013 
#define IDC_ST_BLACKFRAME_BORDER 1014 
#define IDC_ST_WHITEFRAME_SUNKEN_BORDER 1015 
#define IDC_ST_GRAYFRAME_SUNKEN_BORDER 1016 
#define IDC_ST_BLACKFRAME_SUNKEN_BORDER 1017 


7.9.2.3. addlmage 


+-,-"ICON"-+ 
»»--addImage(--id--,-x--,-y--,-cx--,-cy--*---------- *--)----------------------- >< 
+-,-style--+ 


The addImage method adds a static control that displays images. 
Note: After adding the static image control, the programmer will still need to assign an image to the 


control. This is done with either the setlmage() method or the setlcon() methods of the static control. 
This can only be done once the underlying dialog has been created. Meaning in initDialog() or later. 


Arguments: 


id 
The resource ID for the static control. 
X, у, CX, Cy 
The control coordinates 
style 
A list of 0 or more style keywords separated by spaces. If this argument is omitted, the default 


is ICON. 


BITMAP 


A static image control is created that will use a bitmap. If neither BITMAP nor 
METAFILE are specified, the control will be an ICON image control. 


METAFILE 


A static image control that uses an enhanced metafile will be created. If neither BITMAP 
nor METAFILE are specified, the control will be an ICON image control. 
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NOTIFY 


Causes the static control to send notification messages for the click, double click, 
disabled, and enabled events. A static control without this style does not send notification 
messages. See the connectStaticNotify() method of the .MessageExtensions class for 
further information. 


SUNKEN 


The control is drawn with a half-sunken border around it. 


CENTERIMAGE 
Bitmaps are centered in the static control that contains it. The control is not resized, so 
that a bitmap too large for the control will be clipped. 

RIGHTJUST 


The lower right corner of the static control with the BITMAP or ICON style remains fixed 
when the control is resized. Only the top and left sides are adjusted to accommodate a 
new bitmap or icon. 


SIZECONTROL 


Adjusts the bitmap to fit the size of the static control. For example, changing the locale 
can change the system font, and thus controls might be resized. If a static control had a 
bitmap, the bitmap would no longer fit the control. This style bit dictates automatic 
redimensioning of bitmaps to fit their controls. 


If CENTERIMAGE is specified, the bitmap or icon is centered (and clipped if needed). If 
CENTERIMAGE is not specified, the bitmap or icon is stretched or shrunk. 


Note that the redimensioning in the two axes are independent, and the result may have a 
changed aspect ratio. 


SIZEIMAGE 
The actual resource width of the image is used. 


SIZEIMAGE is always used in conjunction with ICON. For icon images, the static 
control is resized accordingly, but the icon remains aligned to the originally specified left 
and top edges of the control. 


Note that if CENTERIMAGE is also specified, the icon is centered within the control’s 
space rectangle. 


HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 


BORDER 


The border window style. 
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GROUP 
The group control style. 


TAB 


The tabstop control style. 


Return value: 


The possible return values are: 


Success. 
less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


This example adds a static image control that uses a bitmap and the control automatically sizes itself 
to the size of the bitmap. 


::method defineDialog 
self~addImage(IDC_BMP_PICTURE, 10, 10, 20, 17, "BITMAP REALSIZEIMAGE") 
self~addStatic(IDC_ST_DESCRIPTION, 14, 190, 176, 20, "TEXT LEFT", "Description") 


self~addButton(IDC_PB_NEXT, 10, 223, 50, 14, "Next", onNext) 
self~addButton(IDOK, 140, 223, 50, 14, "Ok", ok, "DEFAULT") 


7.9.2.4. addWhiteRect 


>>--addWhiteRect (--х-,-у-,-сх-,-су--+----------- +-------- *--)------------------ >< 
+-,--style--+-,--id--+ 


The addWhiteRect() method adds a white rectangle static control to the dialog. The rectangle is filled 
with the current window background color, which is white in the default color scheme. 


Arguments: 


X, y, CX, Cy 


The control coordinates 
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style 


A list of 0 or more of the following style keywords separated by spaces. 


NOTIFY 


Causes the static control to send notification messages for the click, double click, 
disabled, and enabled events. A static control without this style does not send notification 
messages. See the connectStaticNotify() method of the .MessageExtensions class for 
further information. 


SUNKEN 


The control is drawn with a half-sunken border around it. 


HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 


BORDER 


The border window style. 


GROUP 
The group control style. 


TAB 


The tabstop control style. 


The resource ID for the static control. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


See the Frames and Rectangles example. 
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7.9.2.5. addWhiteFrame 


»»--addWhiteFrame(--x-,-y-,-cx-,-cy--*----------- +-------- +--)----------------- >< 
+-,--style--+-,--id--+ 


The addWhiteFrame() method adds a white frame static control to the dialog. The frame is drawn with 


the current window background color, which is white in the default color scheme. 


Arguments: 


X, y, CX, cy 
The control coordinates 
style 


A list of 0 or more of the following style keywords separated by spaces. 


NOTIFY 


Causes the static control to send notification messages for the click, double click, 
disabled, and enabled events. A static control without this style does not send notification 
messages. See the connectStaticNotify() method of the .MessageExtensions class for 
further information. 


SUNKEN 


The control is drawn with a half-sunken border around it. 


HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 


BORDER 


The border window style. 


GROUP 
The group control style. 


TAB 


The tabstop control style. 


The resource ID for the static control. 
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Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


See the Frames and Rectangles example. 


7.9.2.6. addGrayRect 


>>--addGrayRect (--х-,-у-,-сх-,-су--+----------- +-------- *--)------------------- >< 
*-,--style--4-,--id--* 


The addGrayRect() method adds a gray rectangle static control to the dialog. The rectangle is filled with 


the same color as the screen background (desktop), which is gray in the default color scheme. 


Arguments: 


X, y, CX, су 
The control coordinates 


style 


A list of 0 or more of the following style keywords separated by spaces. 


NOTIFY 


Causes the static control to send notification messages for the click, double click, 
disabled, and enabled events. A static control without this style does not send notification 
messages. See the connectStaticNotify() method of the .MessageExtensions class for 
further information. 


SUNKEN 


The control is drawn with a half-sunken border around it. 


HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 
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BORDER 


The border window style. 


GROUP 
The group control style. 


TAB 


The tabstop control style. 


The resource ID for the static control. 


Return value: 


The possible return values are: 


Success. 
less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


See the Frames and Rectangles example. 


7.9.2.7. addGrayFrame 


»»--addGrayFrame(--x-,-y-,-cx-,-cy--*----------- +-------- *--)------------------ >< 
*-,--style--4-,--id--* 


The addGrayFrame() method adds a gray frame static control to the dialog. The frame is drawn with the 
same color as the screen background (desktop), which is gray in the default color scheme. 


Arguments: 


X, y, CX, су 


The control coordinates 
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style 


A list of 0 or more of the following style keywords separated by spaces. 


NOTIFY 


Causes the static control to send notification messages for the click, double click, 
disabled, and enabled events. A static control without this style does not send notification 
messages. See the connectStaticNotify() method of the .MessageExtensions class for 
further information. 


SUNKEN 


The control is drawn with a half-sunken border around it. 


HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 


BORDER 


The border window style. 


GROUP 
The group control style. 


TAB 


The tabstop control style. 


The resource ID for the static control. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


See the Frames and Rectangles example. 
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7.9.2.8. addBlackRect 


>>--addBlackRect (--x-,-y-,-cx-,-cy--*----------- +-------- +--)------------------ >< 
*-,--style--4-,--id--* 


The addBlackRect() method adds a black rectangle static control to the dialog. The rectangle is flled with 


the current window frame color, which is black in the default color scheme. 


Arguments: 


X, y, CX, су 
The control coordinates 
style 


A list of 0 or more of the following style keywords separated by spaces. 


NOTIFY 


Causes the static control to send notification messages for the click, double click, 
disabled, and enabled events. A static control without this style does not send notification 
messages. See the connectStaticNotify() method of the .MessageExtensions class for 
further information. 


SUNKEN 


The control is drawn with a half-sunken border around it. 


HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 


BORDER 


The border window style. 


GROUP 
The group control style. 


TAB 


The tabstop control style. 


The resource ID for the static control. 
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Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


See the Frames and Rectangles example. 


7.9.2.9. addBlackFrame 


»»--addBlackFrame(--x-,-y-,-cx-,-cy--*----------- +-------- e ----------------- >< 
+-,--style--+-,--id--+ 


The addBlackFrame() method adds a black frame static control to the dialog. The rectangle is drawn 


with the current window frame color, which is black in the default color scheme. 


Arguments: 


X, у, CX, су 
The control coordinates 


style 


A list of 0 or more of the following style keywords separated by spaces. 


NOTIFY 


Causes the static control to send notification messages for the click, double click, 
disabled, and enabled events. A static control without this style does not send notification 
messages. See the connectStaticNotify() method of the .MessageExtensions class for 
further information. 


SUNKEN 


The control is drawn with a half-sunken border around it. 


HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 
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BORDER 


The border window style. 


GROUP 
The group control style. 


TAB 


The tabstop control style. 


The resource ID for the static control. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


See the Frames and Rectangles example. 


7.9.2.10. addEtchedFrame 


»»--addEtchedFramed(--x-,-y-,-cx-,-cy--*----------- +-------- +--)--------------- >< 
+-,--style--+-,--id--+ 


The addEtchedFrame() method adds an etched rectangle static control to the dialog. 


Arguments: 


X, у, CX, cy 


The control coordinates 
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style 


A list of 0 or more of the following style keywords separated by spaces. 


NOTIFY 


Causes the static control to send notification messages for the click, double click, 
disabled, and enabled events. A static control without this style does not send notification 
messages. See the connectStaticNotify() method of the .MessageExtensions class for 
further information. 


SUNKEN 


The control is drawn with a half-sunken border around it. 


HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 


BORDER 


The border window style. 


GROUP 
The group control style. 


TAB 


The tabstop control style. 


The resource ID for the static control. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


See the Frames and Rectangles example. 
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7.9.2.11. addEtchedHorizontal 


»»--addEtchedHorizontal(--x-,-y-,-cx-,-cy--*----------- +-------- +--)----------- >< 
+-,--style--+-,--id--+ 


The addEtchedHorizontal() method adds an etched horizontal line static control to the dialog. 


Arguments: 


X, y, CX, cy 
The control coordinates 
style 


A list of 0 or more of the following style keywords separated by spaces. 


NOTIFY 


Causes the static control to send notification messages for the click, double click, 
disabled, and enabled events. A static control without this style does not send notification 
messages. See the connectStaticNotify() method of the .MessageExtensions class for 
further information. 


SUNKEN 


The control is drawn with a half-sunken border around it. 


HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 


BORDER 


The border window style. 


GROUP 
The group control style. 


TAB 


The tabstop control style. 


The resource ID for the static control. 
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Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


See the Frames and Rectangles example. 


7.9.2.12. addEtchedVertical 


>>--addEt chedVertical (--х-,-у-,-сх-,-су--+----------- +-------- +--)------------- >< 
*-,--style--4-,--id--* 


The addEtchedVertical() method adds an etched vertical line static control to the dialog. 


Arguments: 


X, y, CX, су 
The control coordinates 


style 


A list of 0 or more of the following style keywords separated by spaces. 


NOTIFY 


Causes the static control to send notification messages for the click, double click, 
disabled, and enabled events. A static control without this style does not send notification 
messages. See the connectStaticNotify() method of the .MessageExtensions class for 
further information. 


SUNKEN 


The control is drawn with a half-sunken border around it. 


HIDDEN 


The not visible window style. 


DISABLED 


The not enabled window style. 
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BORDER 


The border window style. 


GROUP 
The group control style. 


TAB 


The tabstop control style. 


The resource ID for the static control. 


Return value: 


The possible return values are: 


Success. 
less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


See the Frames and Rectangles example. 


7.9.3. addicon 


»»--addIcon(--id--,--fileName--)----------------------------------------------- >< 


The addIcon method adds an icon resource to the dialog. This is equivalent to using the ICON statement in 
a resource script. 


Arguments: 


The arguments are: 
id 
The resource ID for the icon. 


fileName 


The file name of the icon. If the icon file is not in the current directory, then a relative or fully 
qualified file name should be used. 
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Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


The following example creates a very simple dialog that has an OK button and a static text box. The 
addIcon method is used to load an icon resource using the ID of 15. That icon is then used in the 
execute method for the dialog icon. (The dialog icon is the icon shown in the title bar of the dialog.) 


dlg = .SimpleDialog^new 

if dlg~initCode = 0 then до 
dlg~create(30, 30, 150, 100, "The Simple Dialog", "VISIBLE") 
dlg^execute("SHOWTOP", 105) 
dlg^deinstall 

end 


::requires "OO0DWin32.cls" 
::class SimpleDialog subclass UserDialog 
::method defineDialog 
self~addText(10, 20, 130, 30, "Simple message", "CENTER BORDER", 100) 


self~addButton(IDOK, 105, 70, 35, 15, "OK") 
self~addIcon(105, "MyAppIcon.ico") 


7.9.4. addEntryLine 


>>--аааЕпїгу11пе(-14---+--------+--,--х--,--у--,--сх-,--+------+--+---------+-)-->< 
+-,-паше-+ +-,-cy-+ +-,-style-+ 


The addEntryLine method adds an entry line (an Edit Control in Windows terms) to the dialog. 


Arguments: 


The arguments are: 
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id 
The resource ID for the control. 

name 
The name of the data attribute associated with the dialog item. Using this argument performs 
the same function as the connectEntryLine() method. The documentation connectEntryLine() 
has a good description of the concept of the data attribute. 
If you omitt this argument then the data attribute is constructed automatically and named by 
concatenating the string DATA with the id argument, i.e.: DATA || id. 

X, у, CX, су 
The control coordinates. If cy is omitted, then the height is calculated to fit the height of the 
dialog font. 

style 


A list of 0 or more of the following style keywords separated by spaces: 


Note: The behavior described here for the style keywords may vary slightly depending on the 
version of Windows. 


AUTOSCROLLH READONLY NUMBER 
HSCROLL KEEPSELECTION OEM 
AUTOSCROLLV PASSWORD HIDDEN 
VSCROLL CENTER DISABLED 
MULTILINE RIGHT GROUP 
HIDESELECTION UPPER NOTAB 
NOWANTRETURN LOWER NOBORDER 
AUTOSCROLLH 


Automatically scrolls text to the right when the user types a character at the end of the 
line. In a single-line edit control text can not be added past the width of the control 
without this style. Multi-line edit controls do not need this style if a horizontal scroll bar 
is added. 

HSCROLL 
Adds a horizontal scroll bar to the bottom of the edit control. A horizontal scroll bar is 
only functional in multi-line edit controls. 

AUTOSCROLLV 
Automatically scrolls text up when the user presses ENTER on the last line. This style 
only effects multi-line edit controls and is not needed if a vertical scroll bar is added. 


VSCROLL 


Adds a vertical scroll bar to the right of the edit control. 


MULTILINE 


Designates a multiple-line edit control. (The default is single line.) Multi-line edit 
controls have the WANTRETURN and KEEPSELECTION styles unless the 
NOWANTRETURN and / or HIDESELECTION keywords are specified. 
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When a multi-line edit control has the WANTRETURN style, pressing the ENTER key 
inserts a line break in the text of the control. Without the WANTRETURN style, pressing 
the ENTER key clicks the default button. With the KEEPSELECTION style, any selected 
text in the edit control keeps its highlight when the control loses focus. 
HIDESELECTION 
Removes the KEEPSELECTION style from multi-line edit controls. This keyword only 
effects multi-line edit controls. 
NOWANTRETURN 
Removes the WANTRETURN style from multi-line edit controls. This keyword only 
effects multi-line edit controls. 


READONLY 


Prevents the user from entering or editing text in the edit control. 


KEEPSELECTION 


Selected text in an edit control keeps its highlight when the focus is shifted away from the 
control. 


PASSWORD 


Characters typed into the edit control are masked. Rather than displaying the character 
typed, the edit control displays the mask character. Prior to Windows XP the default mask 
character was the asterisk. In Windows XP the default mask character is a black circle. 
The default password character can be changed by using the PasswordChar= method. 


CENTER 


Centers text in an edit control. (In Windows 95 and NT this style only effects multi-line 
edit controls.) 


RIGHT 


Aligns text flush right in an edit control. (In Windows 95 and NT this style only effects 
multi-line edit controls.) 


UPPER 


Converts all characters to uppercase as they are typed into the edit control. 


LOWER 


Converts all characters to lowercase as they are typed into the edit control. 


NUMBER 


Only allows digits to be typed into the edit control. If the user types an non-digit character 
an information balloon is displayed informing the user that only digits are allowed. This 
style does not prevent the user from pasting non-digits into the control. 
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OEM 


Converts text entered in the edit control from the Windows character set to the OEM 
character set and then back again to the Windows character set. This ensures proper 
character conversion in certain circumstances. Microsoft states that this style is most 
useful when edit controls contain file names that will be used with file systems that do not 
support Unicode. For further details see the Windows documentation provided by 
Microsoft. 


HIDDEN 


Create the edit control without the visible style. 


DISABLED 


Create the edit control without the enabled style. 


GROUP 


Create the edit control with the group style. 


NOTAB 


Create the edit control without the tabstop style. By default the edit control is created with 
the tabstop style. 


NOBORDER 


Create the edit control without the border style. By default edit controls are created with a 
border. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


The following example puts the edit control with ID 201 and length of 150 dialog units close to the 
upper-left corner of the dialog’s client area. The FIRSTNAME attribute is created and connected to 
the dialog item. If the entered data is longer than 150 dialog units, the edit control scrolls 
horizontally. 


MyDialog^addEntryLine(201, "FIRSTNAME", 12, 14, 150, ,"AUTOSCROLLH") 
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7.9.5. addPasswordLine 


>>--аааРавзыогаї1пе(-14---+--------+--,--х--,--у--,--сх-,--+------+--+---------+-)-->< 
+-,-паше-+ +-,-cy-+ +-,-style-+ 


The addPasswordLine method adds a password edit control that does not echo the characters entered but 
displays the password character instead. This method is a convenience method and is used exactly like 
the addEntryLin() method. It simple specifies the PASSWORD style for the programmer. 


Arguments: 


The arguments are: 


id 
The resource ID for the control. 

name 
The name of the data attribute associated with the dialog item. Using this argument performs 
the same function as the connectEntryLine() method. The documentation connectEntryLine() 
has a good description of the concept of the data attribute. 
If you omitt this argument then the data attribute is constructed automatically and named by 
concatenating the string DATA with the id argument, 1.е.: DATA || id. 

X, у, CX, су 
The control coordinates. If cy is omitted, then the height is calculated to fit the height of the 
dialog font. 

style 


A list of 0 or more of the following style keywords separated by spaces: 


Note: The behavior described here for the style keywords may vary slightly depending on the 
version of Windows. 


AUTOSCROLLH READONLY OEM 
HSCROLL KEEPSELECTION HIDDEN 
AUTOSCROLLV CENTER DISABLED 
VSCROLL RIGHT GROUP 
MULTILINE UPPER NOTAB 
HIDESELECTION LOWER NOBORDER 


NOWANTRETURN NUMBER 


AUTOSCROLLH 


Automatically scrolls text to the right when the user types a character at the end of the 
line. In a single-line edit control text can not be added past the width of the control 
without this style. Multi-line edit controls do not need this style if a horizontal scroll bar 
is added. 


HSCROLL 


Adds a horizontal scroll bar to the bottom of the edit control. A horizontal scroll bar is 
only functional in multi-line edit controls. 
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AUTOSCROLLV 
Automatically scrolls text up when the user presses ENTER on the last line. This style 
only effects multi-line edit controls and is not needed if a vertical scroll bar is added. 
VSCROLL 


Adds a vertical scroll bar to the right of the edit control. 


MULTILINE 


Designates a multiple-line edit control. (The default is single line.) Multi-line edit 
controls have the WANTRETURN and KEEPSELECTION styles unless the 
NOWANTRETURN and / or HIDESELECTION keywords are specified. 


When a multi-line edit control has the WANTRETURN style, pressing the ENTER key 
inserts a line break in the text of the control. Without the WANTRETURN style, pressing 
the ENTER key clicks the default button. With the KEEPSELECTION style, any selected 
text in the edit control keeps its highlight when the control loses focus. 


HIDESELECTION 


Removes the KEEPSELECTION style from multi-line edit controls. This keyword only 
effects multi-line edit controls. 


NOWANTRETURN 


Removes the WANTRETURN style from multi-line edit controls. This keyword only 
effects multi-line edit controls. 


READONLY 


Prevents the user from entering or editing text in the edit control. 


KEEPSELECTION 


Selected text in an edit control keeps its highlight when the focus is shifted away from the 
control. 


CENTER 


Centers text in an edit control. (In Windows 95 and NT this style only effects multi-line 
edit controls.) 


RIGHT 


Aligns text flush right in an edit control. (In Windows 95 and NT this style only effects 
multi-line edit controls.) 


UPPER 


Converts all characters to uppercase as they are typed into the edit control. 


LOWER 


Converts all characters to lowercase as they are typed into the edit control. 
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NUMBER 


Only allows digits to be typed into the edit control. If the user types an non-digit character 
an information balloon is displayed informing the user that only digits are allowed. This 
style does not prevent the user from pasting non-digits into the control. 


OEM 


Converts text entered in the edit control from the Windows character set to the OEM 
character set and then back again to the Windows character set. This ensures proper 
character conversion in certain circumstances. Microsoft states that this style is most 
useful when edit controls contain file names that will be used with file systems that do not 
support Unicode. For further details see the Windows documentation provided by 
Microsoft. 


HIDDEN 


Create the edit control without the visible style. 


DISABLED 


Create the edit control without the enabled style. 


GROUP 


Create the edit control with the group style. 


NOTAB 


Create the edit control without the tabstop style. By default the edit control is created with 
the tabstop style. 


NOBORDER 


Create the edit control without the border style. By default edit controls are created with a 
border. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 
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7.9.6. addListBox 


>>--аааї.1в%Вох(--14--,--+------+--,--х--,--у--,--сх--,--су--+--------- +-)------ >< 
+-паше-+ +-,-style-+ 


Adds a list box to the dialog. 


Arguments: 


The arguments are: 
id 
The resource ID for the control. 


name 


The name of the data attribute associated with the dialog item. Using this argument performs 
the same function as the connectListBox() method for single selection list boxes, or the 
connectListBox() method for multi selection list boxes. The documentation for the 
connectEntryLine() method has a good description of the concept of the data attribute. 


If you omitt this argument then the data attribute is constructed automatically and named by 
concatenating the string DATA with the id argument, i.e.: DATA || id. 
X, у, CX, су 


The control coordinates. 


style 


A list of 0 or more of the following style keywords separated by spaces: 


MULTI MCOLUMN GROUP 
NOTIFY PARTIAL DISABLED 
SORT SBALWAYS NOBORDER 
COLUMNS KEYINPUT NOTAB 
VSCROLL EXTSEL 

HSCROLL HIDDEN 


MULTI 


Makes the list box a multiple choice list box, that is, you can select more than one line. 


NOTIFY 


A message is posted whenever the user selects an item of the list box. To use this feature 
you have to connect the list to a method (see ConnectList). 


SORT 


The items in the dialog are listed in the noted order. 


COLUMNS 


The list box can handle tab characters ("09"x). Use this option together with the 
SetListTabulators method (see page SetListTabulators) to have more than one column in a 
list. 


ooRexx OODialog Reference Version 4.0.0 347 


Chapter 7. UserDialog Class 


VSCROLL 


Adds a vertical scroll bar to the list box. Scroll bars appear only if the list contains more 
lines than can fit in the available space. 


HSCROLL 


Adds a horizontal scroll bar to the list box. See also SetListWidth. 


MCOLUMN 


Makes the list box a multicolumn list box that can be scrolled horizontally. 
SetListColumn Width sets the width of the columns. 


PARTIAL 


The size of the list box equals the size specified by the application when it created the list 
box. Windows usually sizes a list box such that the list box does not display partial items. 


SBALWAYS 


The list box shows a disabled scroll bar if there is no need to scroll. If you do not specify 
this option, the scroll bar is hidden when the list box does not contain enough items. 


KEYINPUT 


Specifies that the owner of the list box receives WM_VKEYTOITEM messages whenever 
the user presses a key and the list box has the input focus. This enables an application to 
perform special processing on the keyboard input. 


To take advantage of this style, the programmer would need to use the addUserMsg() 
method to recieve the keyboard event notification. Furture versions of ooDialog may 
support this event directly. 


EXTSEL 


Allows multiple items to be selected by using the SHIFT key and the mouse or special 
key combinations. 


HIDDEN 


Create the control without the visible style. 


DISABLED 


Create the control without the enabled style. 


GROUP 


Create the control with the group style. 


NOTAB 


Create the control without the tabstop style. By default the list box control is created with 
the tabstop style. 
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NOBORDER 


Create the control without the border style. By default list box controls are created with a 
border. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


7.9.7. addComboBox 


>>--аааСошЬоВох(--14--,--+------+--,--х--,--у--,--сх--,--су--+--------- *-)----- >< 
+-паше-+ +-,-style-+ 


The addComboBox method adds a combo box to the dialog. See the Combo Box chapter for more 
information on combo boxes. 


Arguments: 


The arguments are: 


id 
The resource ID for the control. 

name 
The name of the data attribute associated with the dialog item. Using this argument performs 
the same function as the connectComboBox() method. The documentation for the 
connectEntryLine() method has a good description of the concept of the data attribute. 
If you omitt this argument then the data attribute is constructed automatically and named by 
concatenating the string DATA with the id argument, 1.е.: DATA || 14. 

X, у, CX, су 
The control coordinates. 

style 


A list of 0 or more of the following style keywords separated by spaces: 


SIMPLE NOHSCROLL DISABLED 
LIST PARTIAL NOBORDER 
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SORT HIDDEN NOTAB 
VSCROLL GROUP 


SIMPLE 


Adds a simple combo box, which displays the list box at all times. If neither SIMPLE nor 
LIST are specified, the combo box will be a drop-down combo box. 


LIST 


Adds a drop-down list combo box. If neither SIMPLE nor LIST are specified, the combo 
box will be a drop-down combo box. 


SORT 


The items in the list are sorted by the combo box itself. 


VSCROLL 


Adds a vertical scroll bar to the combo box. 


NOHSCROLL 


Normally the ComboBox automatically scrolls the text in an edit control to the right when 
the user types a character at the end of the line. When the NOHSCROLL style is set, only 
text that fits within the rectangular boundary is allowed. 


PARTIAL 


Specifies that the size of the combo box is exactly the size specified by the application 
when it created the combo box. Normally, the system sizes a combo box so that it does 
not display partial items. 


HIDDEN 


Create the control without the visible style. 


DISABLED 


Create the control without the enabled style. 


GROUP 


Create the control with the group style. 


NOTAB 


Create the control without the tabstop style. By default the combobox control is created 
with the tabstop style. 


NOBORDER 


Create the control without the border style. By default combobox controls are created 
with a border. 
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Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


7.9.8. addinput 


»»--addInput (-14-+--------+-,-х-,-у-+-------+-,-сх2-,-+------+-,-фехї----> 
+-,-name-+ *t-,-cxl-t += -су-+ 


a q------------ +-)----------------------------------<-<-----< >< 
+-,-style-+ +-,-idstatic-+ 


The addInput method adds an entry line (an edit control) along with a label (a static text control) to the 
dialog. 


Arguments: 


The arguments are: 


id 
The resource ID for the control. 


name 


The name of the data attribute associated with the edit contorl Using this argument performs 
the same function as the connectEntryLine() method. The documentation for 
connectEntryLine() has a good description of the concept of the data attribute. 


If you omitt this argument then the data attribute is constructed automatically and named by 
concatenating the string DATA with the id argument, 1.е.: DATA || 14. 
X, y, схі, сх2, cy 


The control coordinates. x and y are the position of the upper-left edge of the label. The edit 
control is aligned automatically. 


сх1 is the length of the label. cx2 is the length of the edit control. cy is the height of the edit 
control. If cx1 or cy are omitted, their length is calculated. 

style 
A list of 0 or more of the following style keywords separated by spaces: 


Note: The behavior described here for the style keywords may vary slightly depending on the 
version of Windows. 
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AUTOSCROLLH READONLY NUMBER 
HSCROLL KEEPSELECTION OEM 
AUTOSCROLLV PASSWORD HIDDEN 
VSCROLL CENTER DISABLED 
MULTILINE RIGHT GROUP 
HIDESELECTION UPPER NOTAB 
NOWANTRETURN LOWER NOBORDER 
AUTOSCROLLH 


Automatically scrolls text to the right when the user types a character at the end of the 
line. In a single-line edit control text can not be added past the width of the control 
without this style. Multi-line edit controls do not need this style if a horizontal scroll bar 
is added. 

HSCROLL 
Adds a horizontal scroll bar to the bottom of the edit control. A horizontal scroll bar is 
only functional in multi-line edit controls. 

AUTOSCROLLV 
Automatically scrolls text up when the user presses ENTER on the last line. This style 
only effects multi-line edit controls and is not needed if a vertical scroll bar is added. 


VSCROLL 


Adds a vertical scroll bar to the right of the edit control. 


MULTILINE 


Designates a multiple-line edit control. (The default is single line.) Multi-line edit 
controls have the WANTRETURN and KEEPSELECTION styles unless the 
NOWANTRETURN and / or HIDESELECTION keywords are specified. 


When a multi-line edit control has the WANTRETURN style, pressing the ENTER key 
inserts a line break in the text of the control. Without the WANTRETURN style, pressing 
the ENTER key clicks the default button. With the KEEPSELECTION style, any selected 
text in the edit control keeps its highlight when the control loses focus. 
HIDESELECTION 
Removes the KEEPSELECTION style from multi-line edit controls. This keyword only 
effects multi-line edit controls. 
NOWANTRETURN 
Removes the WANTRETURN style from multi-line edit controls. This keyword only 
effects multi-line edit controls. 


READONLY 


Prevents the user from entering or editing text in the edit control. 
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KEEPSELECTION 
Selected text in an edit control keeps its highlight when the focus is shifted away from the 
control. 

PASSWORD 
Characters typed into the edit control are masked. Rather than displaying the character 
typed, the edit control displays the mask character. Prior to Windows XP the default mask 
character was the asterisk. In Windows XP the default mask character is a black circle. 
The default password character can be changed by using the PasswordChar= method. 

CENTER 
Centers text in an edit control. (In Windows 95 and NT this style only effects multi-line 
edit controls.) 

RIGHT 
Aligns text flush right in an edit control. (In Windows 95 and NT this style only effects 
multi-line edit controls.) 

UPPER 


Converts all characters to uppercase as they are typed into the edit control. 


LOWER 


Converts all characters to lowercase as they are typed into the edit control. 


NUMBER 
Only allows digits to be typed into the edit control. If the user types an non-digit character 
an information balloon is displayed informing the user that only digits are allowed. This 
style does not prevent the user from pasting non-digits into the control. 


OEM 


Converts text entered in the edit control from the Windows character set to the OEM 
character set and then back again to the Windows character set. This ensures proper 
character conversion in certain circumstances. Microsoft states that this style is most 
useful when edit controls contain file names that will be used with file systems that do not 
support Unicode. For further details see the Windows documentation provided by 
Microsoft. 


HIDDEN 


Create the edit control without the visible style. 


DISABLED 


Create the edit control without the enabled style. 


GROUP 


Create the edit control with the group style. 
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NOTAB 
Create the edit control without the tabstop style. By default the edit control is created with 
the tabstop style. 

NOBORDER 


Create the edit control without the border style. By default edit controls are created with a 
border. 


idstatic 


This argument is used to set the resource ID for the label, if one is desired. If omitted, the 
default stactic control ID (-1) is used. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


The following example creates an entry field and the label Your e-mail address (placed on the entry 
field’s left side). It also creates an attribute with the name YOUREMAILADDRESS. The height of 
the elements is calculated. (See Sample Input Field.) 


MyUserDialog”~addInput (402, , 20, 30, , 150, , "Your eMail address") 


Figure 7-4. Sample Input Field 





Your e-mail address | 





7.9.9. addinputGroup 


ү | 
>>--addInputGroup (-id- ,-x- ,-y-+-------+- ,-cx2- ,--text-+-+----------- ъ---------- +-)-->< 
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+-,-сх1-+ +-,-style-+ +-,-idstat-+ 


The addInputGroup method creates a group of one or more edit controls and their static text labels. The 
height for each edit control and its label is calculated automatically. The number of labels in the text 
argument determine how many input lines are added. A group box is optionally place around the input 
lines. 


This method calls addInput() to add each individual input line. 


Arguments: 


The arguments are: 


startid 


The resource ID that is assigned to the first edit control. Consecutive numbers are assigned to 
the other edit controls 


х,у 


Position of the input group’s upper-left coordinates. 


cxl 


Length of the label(s) for the edit control. If omitted, the length is calculated. 


cx2 


The length of the edit control(s). 


text 


The text used for each edit control’s label. The string must consist of single words separated by 
blank spaces. Each word is used as the label for an edit control. Thus, the number of words 
determines the total number of edit controls. 


If you want to use labels that include blanks (for example, "First Name" instead of 
"FirstName"), use the addInputStem() method. 

style 
A list of 0 or more of the following style keywords separated by spaces. 


Note: The behavior described here for the style keywords may vary slightly depending on the 
version of Windows. Also note that every edit control will be added with the style specified. 


AUTOSCROLLH READONLY NUMBER 
HSCROLL KEEPSELECTION OEM 
AUTOSCROLLV PASSWORD HIDDEN 
VSCROLL CENTER DISABLED 
MULTILINE RIGHT GROUP 
HIDESELECTION UPPER NOTAB 
NOWANTRETURN LOWER NOBORDER 
AUTOSCROLLH 


Automatically scrolls text to the right when the user types a character at the end of the 
line. In a single-line edit control text can not be added past the width of the control 
without this style. Multi-line edit controls do not need this style if a horizontal scroll bar 
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is added. 


HSCROLL 
Adds a horizontal scroll bar to the bottom of the edit control. A horizontal scroll bar is 
only functional in multi-line edit controls. 
AUTOSCROLLV 
Automatically scrolls text up when the user presses ENTER on the last line. This style 
only effects multi-line edit controls and is not needed if a vertical scroll bar is added. 
VSCROLL 


Adds a vertical scroll bar to the right of the edit control. 


MULTILINE 


Designates a multiple-line edit control. (The default is single line.) Multi-line edit 
controls have the WANTRETURN and KEEPSELECTION styles unless the 
NOWANTRETURN and / or HIDESELECTION keywords are specified. 


When a multi-line edit control has the WANTRETURN style, pressing the ENTER key 
inserts a line break in the text of the control. Without the WANTRETURN style, pressing 
the ENTER key clicks the default button. With the KEEPSELECTION style, any selected 
text in the edit control keeps its highlight when the control loses focus. 
HIDESELECTION 
Removes the KEEPSELECTION style from multi-line edit controls. This keyword only 
effects multi-line edit controls. 
NOWANTRETURN 
Removes the WANTRETURN style from multi-line edit controls. This keyword only 
effects multi-line edit controls. 
READONLY 


Prevents the user from entering or editing text in the edit control. 


KEEPSELECTION 
Selected text in an edit control keeps its highlight when the focus is shifted away from the 
control. 

PASSWORD 


Characters typed into the edit control are masked. Rather than displaying the character 
typed, the edit control displays the mask character. Prior to Windows XP the default mask 
character was the asterisk. In Windows XP the default mask character is a black circle. 
The default password character can be changed by using the PasswordChar= method. 


CENTER 


Centers text in an edit control. (In Windows 95 and NT this style only effects multi-line 
edit controls.) 
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RIGHT 
Aligns text flush right in an edit control. (In Windows 95 and NT this style only effects 
multi-line edit controls.) 

UPPER 


Converts all characters to uppercase as they are typed into the edit control. 


LOWER 


Converts all characters to lowercase as they are typed into the edit control. 


NUMBER 
Only allows digits to be typed into the edit control. If the user types an non-digit character 
an information balloon is displayed informing the user that only digits are allowed. This 
style does not prevent the user from pasting non-digits into the control. 


OEM 


Converts text entered in the edit control from the Windows character set to the OEM 
character set and then back again to the Windows character set. This ensures proper 
character conversion in certain circumstances. Microsoft states that this style is most 
useful when edit controls contain file names that will be used with file systems that do not 
support Unicode. For further details see the Windows documentation provided by 
Microsoft. 

HIDDEN 


Create the edit control without the visible style. 


DISABLED 


Create the edit control without the enabled style. 


GROUP 


Create the edit control with the group style. 


NOTAB 
Create the edit control without the tabstop style. By default the edit control is created with 
the tabstop style. 

NOBORDER 


The NOBORDER style has a special meaning for this method. It Controls whether or not 
a group box is drawn around the input group. If NOBORDER is used, the group box is 
not used, otherwise it is. 


idstat 


This argument is used to set the resource ID for the first static text control, the label for the first 
edit control. Normally, static text controls are assigned the default (-1) static control ID, and 
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the programmer does not need to specify this argument. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


The following example creates a four-line input group. The single entry lines are accessible by IDs 
301 through 304. 


MyDialog^addInputGroup(301, 20, 20, ,130, "Name FirstName Street City") 


7.9.10. addCombolnput 


>>-1addComboInput (-id-4--------4-,-x-,-y-*-------*-,-cx2-*---------- +---> 
+-,-attr-+ +-,-сх1-+ +-,-clines-+ 


>-- ,--text---+--------- +--+---------- +-)------------------------------- >< 
+-,-style-+ +-,-idstat-+ 


The addComboInput method adds a combo box and a label (a static text control) to the dialog. 


Arguments: 


The arguments are: 
id 
The resource ID for the control. 


attr 


The name of the data attribute associated with the combo box. Using this argument performs 
the same function as the connectComboBox() method. The documentation for 
connectEntryLine() has a good description of the concept of the data attribute. 


If you omitt this argument then the data attribute is constructed automatically and named by 
concatenating the string DATA with the id argument, 1.е.: DATA || 14. 


358 ooRexx OODialog Reference Version 4.0.0 


Chapter 7. UserDialog Class 


X, y, cX1, сх2, cy 
The control coordinates. x and y are the position of the upper-left edge of the label. The combo 
box is aligned automatically. 


сх1 is the length of the label. cx2 is the width of the combo box. clines is the height of the 
combo box in lines. If cx1 or cy are omitted, their values are calculated. 


text 


The text of the label. The label is displayed on the left-hand side of the combo box. 


style 


A list of 0 or more of the following style keywords separated by spaces: 
SIMPLE NOHSCROLL DISABLED 


LIST PARTIAL NOBORDER 
SORT HIDDEN NOTAB 
VSCROLL GROUP 

SIMPLE 


Adds a simple combo box, which displays the list box at all times. If neither SIMPLE nor 
LIST are specified, the combo box will be a drop-down combo box. 


LIST 


Adds a drop-down list combo box. If neither SIMPLE nor LIST are specified, the combo 
box will be a drop-down combo box. 


SORT 


The items in the list are sorted by the combo box itself. 


VSCROLL 


Adds a vertical scroll bar to the combo box. 


NOHSCROLL 


Normally the ComboBox automatically scrolls the text in an edit control to the right when 
the user types a character at the end of the line. When the NOHSCROLL style is set, only 
text that fits within the rectangular boundary is allowed. 


PARTIAL 


Specifies that the size of the combo box is exactly the size specified by the application 
when it created the combo box. Normally, the system sizes a combo box so that it does 


not display partial items. 


HIDDEN 


Create the control without the visible style. 


DISABLED 


Create the control without the enabled style. 
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GROUP 


Create the control with the group style. 


NOTAB 
Create the control without the tabstop style. By default the combobox control is created 
with the tabstop style. 

NOBORDER 


Create the control without the border style. By default combobox controls are created 
with a border. 


idstatic 


This argument is used to set the resource ID for the label, if one is desired. If omitted, the 
default stactic control ID (-1) is used. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


7.9.11. addinputStem 


»»--addInputGroup(-id-,-x-,-y-*-------*-,-cx2-,-text.--*----------- q--—————-- +-)-->< 
+-,-сх1-+ +-,-style-+ +-,-idstat-+ 


The addInputStem method adds a group of input fields to the dialog. The difference between this method 
and the addInputGroup method is that the text for the static text controls, the labels, is passed to the 
method in a stem variable. This makes it possible to use strings containing blank spaces. 


Arguments: 


The arguments are: 


startid 


The resource ID that is assigned to the first edit control. Consecutive numbers are assigned to 
the other edit controls 
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х,у 
Position of the input group’s upper-left coordinates. 

cxl 
Length of the label(s) for the edit control. If omitted, the length is calculated. 

cx2 
The length of the edit control(s). 

text. 
A stem containing the text used for each edit control’s label. The text for the first label is put at 
text.1, the text for the second label at text .2, and so. The number of consecutive numeric 
tails of the stem determines the total number of edit controls. 
The data attribute for each edit control is created from the stem also. The example below 
should make clear how this is done. 

style 


A list of 0 or more of the following style keywords separated by spaces. 


Note: The behavior described here for the style keywords may vary slightly depending on the 
version of Windows. Also note that every edit control will be added with the style specified. 


AUTOSCROLLH READONLY NUMBER 
HSCROLL KEEPSELECTION OEM 
AUTOSCROLLV PASSWORD HIDDEN 
VSCROLL CENTER DISABLED 
MULTILINE RIGHT GROUP 
HIDESELECTION UPPER NOTAB 
NOWANTRETURN LOWER NOBORDER 
AUTOSCROLLH 


Automatically scrolls text to the right when the user types a character at the end of the 
line. In a single-line edit control text can not be added past the width of the control 
without this style. Multi-line edit controls do not need this style if a horizontal scroll bar 
is added. 


HSCROLL 


Adds a horizontal scroll bar to the bottom of the edit control. A horizontal scroll bar is 
only functional in multi-line edit controls. 


AUTOSCROLLV 


Automatically scrolls text up when the user presses ENTER on the last line. This style 
only effects multi-line edit controls and is not needed if a vertical scroll bar is added. 


VSCROLL 


Adds a vertical scroll bar to the right of the edit control. 


MULTILINE 


Designates a multiple-line edit control. (The default is single line.) Multi-line edit 
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controls have the WANTRETURN and KEEPSELECTION styles unless the 
NOWANTRETURN and / or HIDESELECTION keywords are specified. 
When a multi-line edit control has the WANTRETURN style, pressing the ENTER key 
inserts a line break in the text of the control. Without the WANTRETURN style, pressing 
the ENTER key clicks the default button. With the KEEPSELECTION style, any selected 
text in the edit control keeps its highlight when the control loses focus. 

HIDESELECTION 
Removes the KEEPSELECTION style from multi-line edit controls. This keyword only 
effects multi-line edit controls. 

NOWANTRETURN 
Removes the WANTRETURN style from multi-line edit controls. This keyword only 
effects multi-line edit controls. 

READONLY 


Prevents the user from entering or editing text in the edit control. 


KEEPSELECTION 


Selected text in an edit control keeps its highlight when the focus is shifted away from the 
control. 


PASSWORD 


Characters typed into the edit control are masked. Rather than displaying the character 
typed, the edit control displays the mask character. Prior to Windows XP the default mask 
character was the asterisk. In Windows XP the default mask character is a black circle. 
The default password character can be changed by using the PasswordChar= method. 


CENTER 


Centers text in an edit control. (In Windows 95 and NT this style only effects multi-line 
edit controls.) 


RIGHT 


Aligns text flush right in an edit control. (In Windows 95 and NT this style only effects 
multi-line edit controls.) 


UPPER 


Converts all characters to uppercase as they are typed into the edit control. 


LOWER 


Converts all characters to lowercase as they are typed into the edit control. 


NUMBER 


Only allows digits to be typed into the edit control. If the user types an non-digit character 
an information balloon is displayed informing the user that only digits are allowed. This 
style does not prevent the user from pasting non-digits into the control. 
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OEM 


Converts text entered in the edit control from the Windows character set to the OEM 
character set and then back again to the Windows character set. This ensures proper 
character conversion in certain circumstances. Microsoft states that this style is most 
useful when edit controls contain file names that will be used with file systems that do not 
support Unicode. For further details see the Windows documentation provided by 
Microsoft. 


HIDDEN 


Create the edit control without the visible style. 


DISABLED 


Create the edit control without the enabled style. 


GROUP 


Create the edit control with the group style. 


NOTAB 


Create the edit control without the tabstop style. By default the edit control is created with 
the tabstop style. 


NOBORDER 


The NOBORDER style has a special meaning for this method. It controls whether or not 
a group box is drawn around the input group. If NOBORDER is used, the group box is 
not used, otherwise it is. 


idstat 


This argument is used to set the resource ID for the first static text control, the label for the first 
edit control. Normally, static text controls are assigned the default (-1) static control ID, and 
the programmer does not need to specify this argument. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 
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Example: 


The following example shows how to use AddInputStem. It creates a four-line input group. For each 
entry line (with IDs 401 through 404) the text for the label, (the static text control,) is provided by 
the stem variable. 


The labels also provide the attribute name for each edit control. The attribute names will be slightly 
different from the title because the spaces and ampersands are removed. In this example the NAME, 
FIRSTNAME, STREETNUMBER, and CITYZIP attributes are added to the object. 


FNames.1="Name" 
FNames.2="First Name" 
FNames.3="Street & Number" 
FNames.4="City & ZIP" 


MyDialog^addInputStem(401, 20, 20, , 150, FNames.) 


7.9.12. addScrollBar 


»»--addScrollBar(--id--,--x--,--y--,--cx--,--Ccy--*---------- *--)--------------- >< 
+-,-style--+ 


The addScrollBar method adds a scroll bar to the dialog. 
Arguments: 
The arguments are: 
id 
The resource ID for the control. 


X, у, CX, су 


The control coordinates. 


style 


A list of 0 or more of the following style keywords separated by spaces: 
VERTICAL BOTTOMRIGHT DISABLED 


HORIZONTAL HIDDEN BORDER 

TOPLEFT GROUP TAB 

VERTICAL 
The scroll bar is positioned vertically. This is the default if HORIZONTAL is not 
specified. 

HORIZONTAL 


The scroll bar is positioned horizontally. 
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TOPLEFT 


The scroll bar is aligned to the top left of the given rectangle and has a predetermined 
width (if vertical) or height (if horizontal.) 


BOTTOMRIGHT 


The scroll bar is aligned to the bottom right of the given rectangle and has a 
predetermined width (if vertical) or height (if horizontal.) 


HIDDEN 


Create the control without the visible style. 


DISABLED 


Create the control without the enabled style. 


GROUP 


Create the control with the group style. 


TAB 


Create the control with the tabstop style. 


BORDER 


Create the control with the border style. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


7.10. Dialog Control Methods 


The methods described in this section control the execution of the dialog; they are for internal use only. 


7.10.1. Startit 


»»-aUserDialog^StartIt(--4------ *--—----------- 4--)------------- >< 
+-icon-+ +-,--шода1--+ 
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The StartIt method is intended for internal use only. It is used to create a real Windows object based on a 
dialog template. For a RcDialog the template is supplied by a resource script file. For a UserDialog the 


template is created by using the Add... methods. The method is called by the Execute or ExecuteAsync 
methods. 


Internal Use: 
This method is intended for internal use. It can be overridden, although that is not recommended. 


Arguments: 
There are two optional arguments: 
icon 


The resource ID of the icon to be used as the dialog icon. When this argument is omitted the 
default dialog icon is used. 


modal 


If a modal or a modeless dialog is to be created. A value of 0 signals a modal dialog should be 
created. A value of 1, or the string "NOTMODAL" case insignificant, signals a modeless 
dialog should be created. The default is 0. 


7.10.2. Stoplt 


22-aUserDialog StopLt------------—----—---—-----—e eue ---- >< 


The StopIt method is for internal use only. It is the counterpart to the BaseDialog class StopIt method to 
remove the Windows object. 


Protected: 


This method is protected and cannot be called from outside the instance. It can be overwritten, 
although this is not recommended. 


7.11. Menu Methods 


The methods described in this section are for creating dialog menus. 


7.11.1. CreateMenu 


»»-aUserDialog^CreateMenu(--4------- 4--)----------------------- >< 


+-count-+ 
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This method initializes the creation of a menu. When you have finished adding menu items, call 
SetMenu to combine the menu with the dialog. 


Arguments: 


There is only one argument: 


count 


Maximum number of menu items that can be added 


7.11.2. AddPopupMenu 


»»-aUserDialog^AddPopupMenu(--name--,--"--options--"--)-------- >< 


This method adds a popup menu to the menu. 


The last popup menu must have the option "END" specified. 


Arguments: 


The arguments are: 


name 


The name of the popup menu 


options 


GRAYED DISABLED END 


7.11.3. AddMenultem 


»»-aUserDialog^AddMenultem(--name--,--id--,--"--options--"--,--msgToRaise--)--»« 


This method adds a new menu item after the last added item. 


The last menu item in a popup menu must have the option "END" specified. 


Arguments: 


The arguments are: 


name 


The name of the menu item. The name can include &. 
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id 
The ID of the menu item 


options 


GRAYED DISABLED END CHECKED 


msgToRaise 


Method to be called when the menu item is selected. See ConnectMenultem. 
7.11.4. AddMenuSeparator 
»»-aUserDialog^AddMenuS8eparator-------------------------------- >< 


This method adds a menu separator to the menu after the last added item. 


7.11.5. SetMenu 


2»-aUserDialog беъМеш-------------------------<---< >< 


This method adds the menu that was created or loaded for the current dialog to the dialog window. Note 
that the menu needs additional space and therefore displaces the rest of the dialog items. 


7.11.6. LoadMenu 


»»-aUserDialog^LoadMenu(--resfile--,--menuid-------------------- ? 
>--+----------------------------------- SC a >< 
*-,-—---------------- +--+---------- +-+ 


+-"CONNECTITEMS"-+ +-,--count-+ 


This method loads a menu resource out of a resource script. 


To combine the menu with the dialog, you must call SetMenu. 


Arguments: 


The arguments are: 


resfile 


The name of a resource script. 


368 ooRexx OODialog Reference Version 4.0.0 


Chapter 7. UserDialog Class 


menuid 


The ID of the menu resource. 


CONNECTITEMS 


The menu items are automatically connected to methods named after the name of the menu 
item. See LoadItems for further details. 


count 


The maximum number of menu items that can be loaded. 
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The resource definition for a dialog can either be constructed manually, (see the UserDialog Class,) or 
the definition can be read from a file. ooDialog provides two main dialog classes that read their dialog 
definitions from a file: the ResDialog class and the RcDialog class. 


The ResDialog class uses a dialog definition from a binary file and a RcDialog class gets the definition 
from a resource script file. Resource script files are plain text files. In general, both types of files are 
produced by resource editors which allow the user to visually design the dialog in a "What You See Is 
What You Get" manner. Since resource definitions are standardized, resource editors that produce 
Windows compatible files can be used to define dialogs for use with ooDialog. 


8.1. ResDialog Class 


The ResDialog class is designed to be used together with a binary (compiled) resource. Compiled 
resources can be attached a module, which in Windows is a binary executable file. (That is, a file with the 
extension .exe or .dll). It is possible to create a DLL that has no executable code and attach compiled 
resources to it. The common term for this type of DLL is a resource only DLL. A resource only DLL is 
the type of module that makes the most sense to use with the ResDialog class. However, there is no 
reason why any DLL, that has the compiled resource attached to it, could not be used. 


Requires: 


ResDlg.cls is the source file of this class. 


::requires "oodialog.cls" 


Subclass: 


The ResDialog class is a subclass of BaseDialog and therefore inherits all the methods of that class. 


8.1.1. new (Class method) 


»»--new(--module--,--id--4------------- *------------ --)------------ >< 
+-,--DlgData.-+ +-,--hFile-+ 


Instantiates a new ResDialog object. The dialog template for the object is taken from the specified 
module, which normally is a resource only DLL. 
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Arguments: 


The arguments when creating a new dialog instance of this class are: 


module 
The file name of the DLL where the resource is located. 

id 
The ID of the resource. This is an unique number, or sybmbolic ID resolving to the unique 
number. This number is assigned to the dialog template resource when it was created. 


DlgData. 


A stem variable (don’t forget the trailing period) that contains initialization data. 


hFile 


The file name of a header file containing symbolic ID defines for resources. 


Example: 


This sample code creates a new dialog object from the ResDialog class. It uses dialog resource 100 
in the MYDLG.DLL file. The dialog is initialized with the values of the MyDlgData. stem variable. 


MyDlgData.101="1" 
MyDlgData.102-"Please enter your password." 
MyDlgData.103="" 


dlg = ResDialog^new("MYDLG.DLL", 100, MyDlgData.) 
if dlg~initCode <> 0 then do 

say ?The dialog could not be created’ 

return .false 

/* От some other error handling code. */ 
end 


An additional example can be found under the Init method, in the BaseDialog section, that shows 
the use of the dialog data stem and header file arguments in more detail. 


Note: For а ResDialog the InitCode attribute will be -1 after the dialog object is instantiated if the 
resource ID could not be resolved. For other cases where initialization failed the value will be some 
other non-zero value. 


8.1.2. Startlt 


»»-aResDialog^StartIt(--4------ *--—----------- --)------------- >< 
+-icon-+ +-,--шода1--+ 
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The StartIt method is intended for internal use only. It is used to create the real Windows object based on 
the dialog template in the binary resource file. It is called by the Execute or ExecuteAsync methods. 


Internal Use: 


This method is intended for internal use. It can be overridden, although that is not recommended. 


Arguments: 


There are two optional arguments: 


icon 
The resource ID of the icon to be used as the dialog icon. When this argument is omitted the 
default dialog icon is used. 

modal 


If a modal or a modeless dialog is to be created. A value of 0 signals a modal dialog should be 
created. A value of І, or the string "NOTMODAL" case insignificant, signals a modeless 
dialog should be created. The default is 0. 


8.1.3. SetMenu 


»»-aResDialog^SetMenu(--resid--)------------------------------- >< 


The SetMenu method adds a menu resource, that is stored in the same DLL, to the dialog. Note that the 
menu needs additional space and therefore displaces the rest of the dialog items. 


SetMenu can be called in the InitDialog method only. 


Arguments: 


There is only one argument: 


resid 


ID of the menu resource stored in the same DLL as the dialog. 


8.2. RcDialog Class 


The RcDialog class gets its dialog definition from a resource script file. Resource script files are plain 
text files usually produced by a resource editor. The files generally have a file extension of ".rc", but an 
extension of ".dlg" is used by some resource editors. 
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This class subclasses the UserDialog class and has available all the methods of that class. RcDialog is a 
convenience class that uses the Load method of the UserDialog to load the dialog definition from the 
resource script file. The programmer then does not need to worry about the details of how and when to 
load the resource script. There is a slight difference in instantiating the class, and the programmer does 
not need to use the DefineDialog method because the dialog is defined in the resource script. Other than 
that, the RcDialog class is used in the same manner as the UserDialog class. 


Note: Although the programmer does not need to use the Define method, there is nothing preventing 
its use. The Define method could be used at runtime to add additional dialog elements to those 
defined in the resource script. 


Requires: 
RcDialog.cls is the source file for this class. 
: :геди1гез "oodialog.cls" 

Subclass: 


The RcDialog class is a subclass of UserDialog. 


8.2.1. Init 


»»-aRcDialog^Init(--script--,--dlgID--4------------- E essere > 
+-,--dlgData.-+ +-,--hFile-+ 


| meet ccecepe eee . | +-,--expected-+ 
| V | | 
+-"----+-CENTER--------- +-+--"-+ 

+-CONNECTBUTTONS-+ 

+~CONNECTRADIOS--+ 

+~CONNECTCHECKS--+ 


The Init method of the parent class, UserDialog, has been overridden. 


Arguments: 


The arguments when creating a new dialog instance of this class are: 
script 
The name of the resource script file where the dialog is defined. 


dlgID 


The resource ID of the dialog. This is the unique number, or sybmbolic ID, you assigned to the 
(dialog) resource when creating it. 
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dlgData. 
A stem variable (don’t forget the trailing period) that contains initialization data. 

hFile 
The file name of a header file containing the symbolic ID defines for the resources used by the 
program. 

options 


One or more of the keywords listed in the syntax diagram, separated by blanks: 


CENTER 


The dialog is to be positioned in the center of the screen. 


CONNECTBUTTONS 


For each push button a connection to an object method in the RcDialog object is 
established automatically. See ConnectButton for a description of connecting buttons to a 
method. The name for the object method is created by ooDialog and the programmer 
needs to define the object method. The method name will be the button text with all 
spaces, ampersands, and colons removed. 


CONNECTRADIOS 
Similar to CONNECTBUTTONS, but this option will connect the radio buttons to an 


object method. For radio buttons, the created method name will be the button text with all 
spaces, ampersands, and colons removed, prefaced with "ID". 


CONNECTCHECKS 


Exactly the same as CONNECTRADIOS, for check box controls. The object method 
name is generated in the same way as it is for radio buttons. 


expected 


This is the maximum number of dialog elements the dialog object can handle. See the Create 
method for details. The default value for this argument is 200. 


Example: 


This example creates a new dialog object using the SimpleLB class, which subclasses the RcDialog. 
It uses the dialog defintion with symbolic ID IDD. DIALOG1 in the listBox.rc resource script file. 
The dialog is initialized so that the "Doctor" item is selected in the list box with symbolic ID of 
IDC_LB by using the dlgData. stem variable. The symbolic IDs for this program are contained in the 
"resource.h" file. When the user closes the dialog, Ше dlgData.IDC_LB variable will contain the text 
of the selected item in the list box. 


/* Simple ListBox using a .rc file for the dialog definition */ 
dlgData.IDC LB - "Doctor" 


dlg = .SimpleLB^new("listBox.rc", IDD_DIALOG1, dlgData., "resource.h") 
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if dlg~initCode = 0 then do 
др” Execute ("SHOWTOP") 
dlg^Deinstall 
end 
else do 
say "Problem creating the dialog. Init code:" dlg^initCode 
return 99 
end 


say "The user’s choosen profession is" dlgData.IDC LB 
return 0 
-- End of entry point. 


::requires "QODWIN32.CLS" 
::class SimpleLB subclass RcDialog inherit AdvancedControls 
::method initDialog 


lb = self^getListBox(IDC LB) 


lb^add("Business Manager" ) 
lb^add("Software Developer") 
lb^add("Accountant") 
lb^add("Lawyer") 


lb^add("Doctor") 





To try the example, cut and paste the above code into a file named listBox.rex and paste the 
following code into files listBox.rc and resource.h. 


/* listBox.rc */ 

include <windows.h> 
#include <commctrl.h> 
#include "resource.h" 


IDD_DIALOG1 DIALOGEX 30,30,179,182 

STYLE DS_MODALFRAME | DS_FIXEDSYS | WS_VISIBLE | WS_CAPTION | WS_POPUP | WS_SYSMENU 
CAPTION "List Box Example" 

FONT 8,"MS Shell Dlg 2",400,0,1 


BEGIN 
DEFPUSHBUTTON "Close", IDOK,122,161,50,14 
LISTBOX IDC_LB,8,28,163,122,WS_TABSTOP | LBS_NOINTEGRALHEIGHT | LBS_SORT 
CTEXT "Pick Your Choosen Profession", IDC_STATIC,26,13,122,9 

END 


/* resource.h */ 
#ifndef IDC_STATIC 
#define IDC_STATIC (-1) 


#endif 
#define IDD_DIALOG1 100 
#define IDC_LB 1001 
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The CategoryDialog class creates and controls a dialog that has more than one panel. It is similar to the 
notebook control available in OS/2 or the property sheet available in the Windows 95 user interface. 


Depending on the style you choose, you can switch among different pages by either clicking radio 
buttons or selecting an item from a drop down list. Each page has its own window controls. 


Requires: 
CatDlg.cls is the source file of this class. 
::requires "oodialog.cls" 

Subclass: 


The CategoryDialog class is a subclass of UserDialog (see UserDialog Class). 


Attributes: 


Instances of the CategoryDialog class have the following attributes: 


Catalog 


A directory describing the layout and behavior of the dialog. This directory is usually set up in 
the InitCategories method of the dialog (see InitCategories for more information). 


StaticID 


An internal counter 


Methods: 


Instances of the CategoryDialog class implement the methods listed in the following table. 


Note: In fact, most of the methods do the same as the methods in the parent class, UserDialog, 
except that they are enabled to work with a category dialog. 






































Method... ..оп page 
AddCategoryComboEntry AddCategoryComboEntry 
AddCategoryListEntry AddCategoryListEntry 
CategoryComboAddDirectory CategoryComboAddDirectory 
CategoryComboDrop CategoryComboDrop 
CategoryListAddDirectory CategoryListAddDirectory 
CategoryListDrop CategoryListDrop 
CategoryPage CategoryPage 
ChangeCategoryComboEntry ChangeCategoryComboEntry 
ChangeCategoryListEntry ChangeCategoryListEntry 
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Method... ...0n page 
ChangePage ChangePage 
CreateCategoryDialog CreateCategoryDialog 
CurrentCategory CurrentCategory 
DefineDialog DefineDialog 





DeleteCategoryComboEntry 


DeleteCategoryComboEntry 





DeleteCategoryListEntry 


DeleteCategoryListEntry 















































DisableCategoryItem DisableCategoryItem 
EnableCategoryItem EnableCategoryItem 
FindCategoryComboEntry FindCategoryComboEntry 
FindCategoryListEntry FindCategoryListEntry 
FocusCategoryItem FocusCategorylItem 
GetCategoryAttrib GetCategoryAttrib 
GetCategoryCheckBox GetCategoryCheckBox 
GetCategoryComboEntry GetCategoryComboEntry 
GetCategoryComboltems GetCategoryComboltems 
GetCategoryComboLine GetCategoryComboLine 
GetCategoryEntryLine GetCategoryEntryLine 
GetCategoryListEntry GetCategoryListEntry 
GetCategoryListItems GetCategoryListItems 
GetCategoryListLine GetCategoryListLine 
GetCategoryMultiList GetCategoryMultiList 





GetCategoryRadioButton 


GetCategoryRadioButton 





GetCategory Value 


GetCategory Value 





GetCurrentCategoryComboIndex 


GetCurrentCategoryComboIndex 





GetCurrentCategoryListIndex 


GetCurrentCategoryListIndex 

















GetSelectedPage GetSelectedPage 
HideCategoryItem HideCategoryItem 
Init Init 

InitCategories InitCategories 
InitDialog InitDialog 





InsertCategoryComboEntry 


InsertCategoryComboEntry 





InsertCategoryListEntry 


InsertCategoryListEntry 

















MoveCategoryItem MoveCategoryItem 
NextPage NextPage 
PageHasChanged PageHasChanged 
PreviousPage PreviousPage 
ResizeCategoryItem ResizeCategoryItem 





SendMessageToCategoryItem 


SendMessageToCategoryItem 








SetCategoryAttrib 





SetCategoryAttrib 
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Method... ..оп page 
SetCategoryCheckBox SetCategoryCheckBox 
SetCategoryComboLine SetCategoryComboLine 
SetCategoryEntryLine SetCategoryEntryLine 
SetCategoryItemFont SetCategoryItemFont 
SetCategoryListLine SetCategoryListLine 
SetCategoryListTabulators SetCategoryListTabulators 
SetCategoryMultiList SetCategoryMultiList 
SetCategoryRadioButton SetCategoryRadioButton 
SetCategoryStaticText SetCategoryStaticText 
SetCategory Value SetCategory Value 
SetCurrentCategoryComboIndex SetCurrentCategoryComboIndex 
SetCurrentCategoryListIndex SetCurrentCategoryListIndex 
ShowCategoryItem ShowCategoryItem 

Startlt Startlt 








9.1. Setting Up the Dialog 


The following methods are used to set up the pages of the dialog and start it. 


9.1.1. Init 


>>-аСаўедогур1а1од^71п1%(--+----------+--,--+------+--,--+------+--,--+-------+--,--> 
+-DlgData.-+ +-саїх-+ +-сату-+ +-саїсх-+ 
>--+-------------------- +--,--+---------- +--,--+---------- +--,--+-------- +--,------ > 
+-"--+-DROPDOWN-+--"-+ +-cattable-+ +-catlabel-+ +-catmax-+ 


+-TOPLINE--+ 
+-WIZARD---+ 


The Init method initializes the category dialog object. 


Arguments: 


The arguments are: 


DlgData. 


A stem variable (do not forget the trailing period) that contains initialization data for some or 
all dialog items. If the dialog is terminated by means of the OK button, the values of the 
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dialog’s data fields are copied to this variable. The ID of the dialog items is used to name the 
entry within the stem. 

catx, caty 
The position of the category selection control group (radio buttons or combo box). The defaults 
are 10 and 4. 

catcx 


This argument sets the length of one item of the control group (calculated if omitted) 


style 


This argument determines the style of the category dialog. Without one of the following 
keywords, the category selection is done by a vertical radio button group: 


DROPDOWN 


Creates a drop-down list at the top (useful if there are many categories) 


TOPLINE 


Draws a horizontal radio button group at the top of the client area 


WIZARD 
Adds Backward and Forward buttons with IDs 11 and 12 to switch between category 
pages 
Without DROPDOWN and TOPLINE the default category selection is done by a vertical radio 
button group, with the dialog pages to the right of the radio buttons. 
cattable 
This argument can be used to set the category names separated by blanks. If omitted, set the 
category names in the InitCategories method. 
catlabel 


This argument defines the label for the combo box in DROPDOWN style (default is "Page:") 


catmax 
This argument sets the split point of the radio button group in default style, or the number of 
entries in the combo box drop-down list. 

hFile 


The file name of a header file containing symbolic ID defines for resources. 


Example: 
The following example creates a category dialog, using a combo box as the selection control: 


dlg = MyCategoryDialog^new(MyData., , , ,"DROPDOWN", , 
"Movies Cinemas Days Ticket","Dialog panel:") 
dlg^createCenter(200,180,"Let's go to the movies") 
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dlg~ execute ("SHOWTOP") 
СТРА MyCategoryDialog subclass CategoryDialog 
::method Movies /* define the Movies page */ 


::method Cinemas /* define the Cinemas page */ 


An additional example can be found under the Init method, in the BaseDialog section. This 
example shows the use of the dialog data stem and header file arguments in more detail. 


9.1.2. InitCategories 


»»-aCategoryDialog InitCategories------------------------------ >< 


The InitCategories method is called by Init to set the characteristics of the category dialog. 


Protected: 


This method is protected. 


Catalog directory: 


The InitCategories should set up the Catalog directory with information about the layout and the 
behavior of the dialog. The directory entries are: 


names 


An array containing the names of the categories. The array is initialized with the names given 
in the Init method (argument cattable). These names are used as labels for page selection 
control and as messages sent to the object to define the single pages. 


Your subclass must provide a method for each category page--with the same name as the label 
in this directory--to define the dialog page using LoadItems to load the dialog items from а 
resource script or Add... methods. Notice that blanks are removed when you call the Define... 
methods. 


If your subclass provides methods with the prefix Init followed by the name of the categories 
(blanks removed), these methods are called by InitDialog to initialize the dialog (each page is a 
dialog) that contains the corresponding category. 


Unless you already specified the categories with the Init method, you must assign an array to 
this Catalog entry. 


count 


Number of categories 


handles 


For internal use only 
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id 
For internal use only 


category 


For internal use only 


page 


A directory with the following entries: 


font 


Name of the font used for the dialog 


fsize 


Size of the font 
style 
Style of the dialog (see Create) 


expected 


Total number of expected dialog items of all category pages (200) 


btnwidth 
Width of Backward and Forward push buttons (see WIZARD in Init method) 


leftbtntext 


Alternate label of Backward button 


rightbtntext 
Alternate label of Forward button 


The next four entries should not be modified: 


x 
Horizontal position of the category pages relative to the parent dialog 
y 
Vertical position of the category pages relative to the parent dialog 
w 
Width of the category pages 
h 


Height of the category pages 
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Example: 


The following example sets the category names to Text Editor, Compiler, Linker, and Debugger. 
The subclass of CategoryDialog must define four methods named after them. 


:class MyCategoryDialog subclass CategoryDialog 

::method InitCategories 
self^catalog["names"]- .array~of("Text Editor","Compiler","Linker", , 
"Debugger" ) 
self^catalog["page"]["leftbtntext"] = "&Previous" 
self^catalog["page"]["rightbtntext"] = "&Next" 


::method TextEditor /* blanks are removed when the message is sent 


from DefineDialog */ 
/* add control to the first page */ 


::method Compiler 


::method InitTextEditor /* called by InitDialog */ 
/* initialize the first dialog */ 


9.1.3. DefineDialog 


»»-aCategoryDialog^DefineDialog-------------------------------- >< 


The DefineDialog method is called after the main dialog has been created. This method must not be 
overwritten in a subclass because it defines the layout of the frame window and calls the definition 
methods for each category page. 


Protected: 


This method is protected. 


Example: 


Assume that you have the categories "Common Data", "Company Data", and "Special". The 
following methods are automatically called by DefineDialog to add dialog items to the associated 


page: 


CommonData 


to add controls to the first category page. 


ooRexx OODialog Reference Version 4.0.0 383 


Chapter 9. CategoryDialog Class 


CompanyData 


to add controls to the second category page. 


Special 
to add controls to the third category page. 


See InitCategories for more information. 


9.1.4. CategoryPage 


»»-aCategoryDialog CategoryPage-------------------------------- >< 


The CategoryPage method adds controls to the base window of a Category Dialog. It is used to define the 
layout of the parent dialog that contains the single pages. 


Protected: 


This method is protected and should not be overwritten or called. Use the InitCategories method to 
set up the dialog. 


9.1.5. CreateCategoryDialog 


>>-aCategoryDialog~CreateCategoryDialog(--x-- ,--y-- ,--cx--,--cy--,--> 
>--+---------- S +--,--options--,--expected--)--->< 
+-fontName-+ +-fontSize-+ 


The CreateCategoryDialog method creates the category dialog. 


Protected: 


This method is protected. It is called by another method and usually does not have to be called 
manually. 


9.1.6. InitDialog 


»»-aCategoryDialog^InitDialog---------------------------------- >< 


The InitDialog method is called after the Windows dialog has been created and before the category 
dialog is to be displayed. 


Do not override this method to initialize your category dialog pages but define an Init... method for each 
of your pages that you want to initialize like adding combo and list box items. If your subclassed dialog 
defines a method that has the prefix "Init" followed by the name of the category (without blanks), this 
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method is called by InitDialog to handle the initialization of the corresponding page. If you use a method 
that requires a category specifier, such as AddCategoryComboEntry or GetTreeControl, and you omit the 
category, OODialog assumes that the dialog item addressed is part of the page that contains the current 
category. 


Protected: 
This method is protected. 


Example: 


Assume that you have the categories "Common Data", "Company Data", and "Special". The 
following methods are automatically called when provided by the subclass: 


InitCommonData 
to initialize the first category. 


InitCompanyData 


to initialize the second category. 


InitSpecial 
to initialize the third category. 


See InitCategories for more information. 


9.1.7. GetSelectedPage 


»»-aCategoryDialog^GetSelectedPage----------------------------- >< 


The GetSelectedPage method is used internally to return the currently selected page using the combo box 
or radio buttons (1 indicates the first page). 


9.1.8. CurrentCategory 
»»-aCategoryDialog CurrentCategory----------------------------- >< 
The CurrentCategory method returns the number of the current dialog page. The first page is numbered 1. 


Example: 
The following example tests the current page number: 


if MyCategoryDialog CurrentCategory-2 then до... 
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9.1.9. NextPage 


»»-aCategoryDialog^NextPage------------------------------------ >< 


The NextPage method switches the dialog to the next category page. 


9.1.10. PreviousPage 


»»-aCategoryDialog^PreviousPage-------------------------------- >< 


The PreviousPage method switches the dialog to the previous category page. 


9.1.11. ChangePage 


»»-aCategoryDialog^ChangePage(--4--------- +--) ----------------- >< 
+-NewPage-+ 


The ChangePage method switches the dialog to another page and returns the new page number. It is also 
called by selection control to activate the selected page. ChangePage invokes PageHasChanged after the 
new page is activated. 


Arguments: 


The only argument is: 


NewPage 


The page number of the new page (default is the page selected by the combo box or radio 
button) 


Example: 
The following example activates the second category page: 


MyCategoryDialog^ChangePage (2) 


9.1.12. PageHasChanged 


»»-aCategoryDialog^PageHasChanged(--oldpage--,--newpage--)----- >< 


The PageHasChanged method is invoked by ChangePage when a new page is activated. The default 
implementation returns without an action. The user can override this method to react to page changes. 
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Arguments: 


The arguments are: 


oldpage 


The page number of the previous page 


newpage 


The page number of the new page 


9.1.13. Startlt 


>>-aCategoryDialog Dtartlt----------------------c--cuecceececceoe >< 


The StartIt method is called by the Execute or ExecuteAsync methods to create a real Windows object 
based on a dialog template. In the CategoryDialog class the Windows object(s) are created in the 

Def ineDialog method. Therefore, the StartIt method is overridden in this class to change the default 
behavior of the superclass. (If unchanged the superclass would create a second duplicate Windows object 
from the dialog template.) 


You might override this method in your subclass, but be sure to forward the message to the parent 
method and to return the result to the caller. 


Example: 
This is a template for overridding this method: 


::class MyCatDlg subclass CategoryDialog 
::method StartIt 
say "this is method "StartIt" !" 
self~StartIt:super() 
handle = result 


return handle 


9.2. Connect... Methods 


»»-aCategoryDialog^Connect...(--id--,--fname--)---------------- >< 


The Connect... methods connect data dialog items of certain types with the dialog object. The Connect... 
methods should be placed into the user-defined methods with the names of the categories defined in the 
InitCategories method. The Connect... methods are defined for the BaseDialog class. For more 
information, see BaseDialog Class. 
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Arguments: 


The arguments are: 


id 
The ID of the dialog item 


fname 


The name of the object attribute 


Example: 


The following example connects an entry line in the Movies page with the FIRSTNAME object 
attribute: 
::method InitCategories 


self^catalog["names"] = .array^of("Movies",...) 


::method Movies 
self^ConnectEntryLine(101, "FIRSTNAME") 


Note: IDs for dialog elements need not be unique across all pages. However, IDs for buttons and list 
boxes that are connected to methods must be unique for the whole category dialog. 


9.3. Methods for Dialog Items 
The methods listed in this section deal with individual dialog items on one of the pages of the category 
dialog. 


The methods correspond to methods with similar names of the BaseDialog class; the word Category is 
inserted between the verb and the dialog item in the method name. For example, 
AddCategoryComboEntry for the CategoryDialog class has the same function as AddComboEntry of the 
BaseDialog class. 


Note: The methods listed here have the same parameters as the corresponding methods of the 
BaseDialog class, with the number of the category page as an extra parameter. 


Another way to directly address dialog items of a category dialog is to retrieve an object of the 
DialogControl class (see page DialogControl Class) or one of its derivates that is associated with the 
requested dialog control. To retrieve such an object, you can call one of the following methods 
depending on the requested control: 


* GetStaticControl 
* GetEditControl 


* GetButtonControl 
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* GetRadioControl 
* GetCheckControl 
* GetListBox 

* GetComboBox 
* GetScrollBar 

* GetTreeControl 
* GetListControl 
* getProgressBar 
* GetSliderControl 
* GetTabControl 


To use these methods and the resulting objects, your category dialog must inherit from the mixin class 
AdvancedControls. You can do this by adding the keyword "inherit" followed by the mixin class name 
"AdvancedControls". For example: 


::class MyCategory subclass CategoryDialog public inherit AdvancedControls 


9.4. Get and Set Methods 


The following sections describe the individual Get and Set methods. 


9.4.1. SetCategoryStaticText 


»»-aCategoryDialog^SetCategoryStaticText(--id--,--data--,--category--^ 


»--)----------------------------------------------------------- >< 


For more information, see SetStaticText. 


9.4.2. GetCategoryEntryLine 


>>-aCategoryDialog~GetCategoryEntryLine(--id-- ,--category--)--->< 


For more information, see GetEntryLine. 


9.4.3. SetCategoryEntryLine 


»»-aCategoryDialog^SetCategoryEntryLine(--id--,--data--,--category--» 
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»--)----------------------------------------------------------- >< 


For more information, see SetEntryLine. 


9.4.4. GetCategoryListLine 


»»-aCategoryDialog^GetCategoryListLine(--id--,--category--)----»« 


For more information, see GetListLine. 


9.4.5. SetCategoryListLine 


»»-aCategoryDialog^SetCategoryListLine(--id--,--data--,--category--)-»« 


For more information, see SetListLine. 


9.4.6. GetCategoryListWidth 


>>-aCategoryDialog~GetCategoryListWidth(--id-- ,--category--)--->< 


For more information, see GetListWidth. 


9.4.7. SetCategoryListWidth 


>>-aCategoryDialog~SetCategoryListWidth(--id-- ,--scrollwidth-- ,--category--)->< 


For more information, see SetListWidth. 


9.4.8. GetCategoryMultiList 


>>-aCategoryDialog~GetCategoryMultiList (--id-- ,--category--)--->< 


For more information, see GetMultiList. 
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9.4.9. SetCategoryMultiList 


»»-aCategoryDialog^SetCategoryMultiList (--id-- ,--data--,--category--> 


>--)-------------------------------------- --------------< >< 


For more information, see SetMultiList. 


9.4.10. GetCategoryComboLine 


>>-aCategoryDialog~GetCategoryComboLine(--id-- ,--category--)--->< 


For more information, see GetComboLine. 


9.4.11. SetCategoryComboLine 
>>-aCategoryDialog~SetCategoryComboLine(--id-- ,--data-- ,--category--> 


»--)----------------------------------------------------------- >< 


For more information, see SetComboLine. 


9.4.12. GetCategoryRadioButton 


>>-aCategoryDialog~GetCategoryRadioButton(--id-- ,--category--)->< 


For more information, see GetRadioButton. 


9.4.13. SetCategoryRadioButton 


»»-aCategoryDialog^SetCategoryRadioButton(--id--,--data--,------ > 


»--category--)------------------------------------------------- >< 


For more information, see SetRadioButton. 


9.4.14. GetCategoryCheckBox 


>>-aCategoryDialog~GetCategoryCheckBox (--id-- ,--category--)---->< 
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For more information, see GetCheckBox. 


9.4.15. SetCategoryCheckBox 


»»-aCategoryDialog^SetCategoryCheckBox(--id--,--data--,--category--» 


»--)----------------------------------------------------------- >< 


For more information, see SetCheckBox. 


9.4.16. GetCategoryValue 


»»-aCategoryDialog^GetCategoryValue(--id--,--category--)------- >< 


For more information, see Get Value. 


9.4.17. SetCategoryValue 


»»-aCategoryDialog^SetCategoryValue(--id--,--data--,--category--)-5« 


For more information, see SetValue. 


9.4.18. GetCategoryAttrib 


»»-aCategoryDialog^GetCategoryAttrib(--aname--,--category--)---»« 


For more information, see GetAttrib. 


9.4.19. SetCategoryAttrib 


»»-aCategoryDialog^SetCategoryAttrib(--attributename--,--category--)-»^« 


For more information, see SetAttrib. 
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9.5. Combo Box Methods 


The following sections describe the individual combo box methods. 


9.5.1. AddCategoryComboEntry 


»»-aCategoryDialog^AddCategoryComboEntry (--id-- ,--data-- ,--category--> 


»--)----------------------------------------------------------- >< 


For more information, see AddComboEntry. 


Arguments: 


The arguments are: 
id 
The ID of the combo box 


data 


The text string that is added to the combo box 


category 


The category page number where the combo box is located 


Example: 


The following example adds a text string to the list of the combo box 101 in the third category page. 


MyCategoryDialog^AddCategoryComboEntry(101, "I'm one of the choices", 3) 


9.5.2. InsertCategoryComboEntry 


>>-aCategoryDialog” InsertCategoryComboEntry (--id-- ,--item-- ,--data-- ,--> 


»--category--)------------------------------------------------- >< 


For more information, see InsertComboEntry. 


9.5.3. DeleteCategoryComboEntry 


>>-aCategoryDialog~DeleteCategoryComboEntry (--id-- ,--index-- ,---> 


»--category--)------------------------------------------------- >< 


ooRexx OODialog Reference Version 4.0.0 393 


Chapter 9. CategoryDialog Class 


For more information, see method DeleteComboEntry. 


9.5.4. FindCategoryComboEntry 


»»-aCategoryDialog^FindCategoryComboEntry (--id--,--data--,------ > 


»--category--)------------------------------------------------- >< 


For more information, see FindComboEntry. 


9.5.5. GetCategoryComboEntry 


>>-aCategoryDialog~GetCategoryComboEntry (--id--,--index--)----- >< 


For more information, see GetComboEntry. 


9.5.6. GetCategoryComboltems 


>>-aCategoryDialog~GetCategoryCombolItems (--ій-- ,--category-—)-->< 


For more information, see GetComboltems. 


9.5.7. GetCurrentCategoryCombolndex 


»»-aCategoryDialog^GetCurrentCategoryComboIndex(--id--,--category--» 


>--)---------------------------------------------------< >< 


For more information, see GetCurrentComboIndex. 


9.5.8. SetCurrentCategoryCombolndex 


»»-aCategoryDialog^SetCurrentCategoryComboIndex(--id--,--4------- +==> 
+-іпаех-+ 


»--,--category--)---------------------------------------------- >< 


For more information, see SetCurrentCombolIndex. 
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9.5.9. ChangeCategoryComboEntry 


»»-aCategoryDialog^ChangeCategoryComboEntry(--id--,--item--,--data--» 


»--,--category--)---------------------------------------------- >< 


For more information, see ChangeComboEntry. 


9.5.10. CategoryComboAddDirectory 


»»-aCategoryDialog^CategoryComboAddDirectory (--id--,--drvpath--,--» 


»--fileAttributes--,--category--)------------------------------ >< 


For more information, see ComboAddDirectory. 


9.5.11. CategoryComboDrop 


»»-aCategoryDialog^CategoryComboDrop(--id--,--category--)------ >< 


For more information, see ComboDrop. 


9.6. List Box Methods 


The following sections describe the individual list box methods. 


9.6.1. AddCategoryListEntry 


»»-aCategoryDialog^AddCategoryListEntry (--id-- ,--data-- ,--category--> 


»--)----------------------------------------------------------- >< 


For more information, see AddListEntry. 


9.6.2. InsertCategoryListEntry 


>>-aCategoryDialog” InsertCategoryListEntry (--id--,--item--,--data--> 


»--,--category--)---------------------------------------------- >< 
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For more information, see InsertListEntry. 


9.6.3. DeleteCategoryListEntry 


>>-aCategoryDialog~DeleteCategoryListEntry (--id-- ,--index-- ,----> 


»--category--)------------------------------------------------- >< 


For more information, see DeleteListEntry. 


9.6.4. FindCategoryListEntry 


»»-aCategoryDialog^FindCategoryListEntry (--id--,--data-- ,--category--> 


»--)----------------------------------------------------------- >< 


For more information, see FindListEntry. 


9.6.5. GetCategoryListEntry 


»»-aCategoryDialog^GetCategoryListEntry (--id-- ,--ndx-- ,--category--> 


»--)----------------------------------------------------------- >< 


For more information, see GetListEntry. 


9.6.6. GetCategoryListltems 


>>-aCategoryDialog~GetCategoryListItems (--id-- ,--category--)--->< 


For more information, see GetListItems. 


9.6.7. GetCurrentCategoryListlndex 


»»-aCategoryDialog^GetCurrentCategoryListIndex(--id--,--category--)-»« 


For more information, see GetCurrentListIndex. 
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9.6.8. SetCurrentCategoryListindex 


»»-aCategoryDialog^SetCurrentCategoryListIndex(--id--,--4------- ==> 
*-index-* 


»--,--category--)---------------------------------------------- >< 


For more information, see SetCurrentListIndex. 


9.6.9. ChangeCategoryListEntry 
>>-aCategoryDialog~ ChangeCategoryListEntry (--id-- ,--item--,--data--> 


»--,--category--)---------------------------------------------- >< 


For more information, see ChangeListEntry. 


9.6.10. SetCategoryListTabulators 


+-,---+ 
ү | 
»»-aCategoryDialog^SetCategoryListTabulators(--id--,----tab-4---» 


»--,--category--)---------------------------------------------- >< 


For more information, see SetListTabulators. 


9.6.11. CategoryListAddDirectory 
»»-aCategoryDialog^CategoryListAddDirectory(--id--,--drvpath--,--» 


»--fileAttributes--,--category--)------------------------------ >< 


For more information, see ListAddDirectory. 


9.6.12. CategoryListDrop 


»»-aCategoryDialog^CategoryListDrop(--id--,--category--)------- >< 


For more information, see ListDrop. 
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9.7. Appearance Modification Methods 


The following sections describe the methods affecting the appearance of the item. 


9.7.1. EnableCategoryltem 


»»-aCategoryDialog^EnableCategoryItem(--id--,--category--)----- >< 


For more information, see EnablelItem. 


9.7.2. DisableCategoryltem 


»»-aCategoryDialog^DisableCategoryltem(--id--,--category--)----»« 


For more information, see DisableItem. 


9.7.3. ShowCategoryltem 


»»-aCategoryDialog^ShowCategoryltem(--id--,--category--)------- >< 


For more information, see ShowItem. 


9.7.4. HideCategoryltem 


»»-aCategoryDialog HideCategoryltem(--id--,--category--)------- >< 


For more information, see Hideltem. 


9.7.5. SetCategoryltemFont 


>>-aCategoryDialog~SetCategoryItemFont (--id-- ,--fonthandle-- ,--redraw-- ,--> 


»--category--)------------------------------------------------- >< 


For more information, see SetItemFont. 
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9.7.6. FocusCategoryltem 


»»-aCategoryDialog^FocusCategoryltem(--id--,--category--)------ >< 


For more information, see FocusItem. 


9.7.7. ResizeCategoryltem 

»»-aCategoryDialog^ResizeCategoryItem(--id--,--width--,--height--,--» 

»--—4---------------------- *--,--category--)-------------------- >< 
+-"--+-HIDEWINDOW-+--"-+ 


+-SHOWWINDOW-+ 
+-NOREDRAW---+ 


For more information, see Resizeltem. 


9.7.8. MoveCategoryltem 


>>-aCategoryDialog~MoveCategoryItem(--id-- ,--xPos-- ,--yPos-- ,---> 


>--+---------------------- *--,--category--)-------------------- >< 
+-"--+-HIDEWINDOW-+--"-+ 
+-SHOWWINDOW-+ 
+-NOREDRAW---+ 


For more information, see Moveltem. 


9.7.9. SendMessageToCategoryltem 
>>-aCategoryDialog~SendMessageToCategoryItem(--id-- ,--msg-- ,--wp-- ,--lp--> 


»--,--category--)---------------------------------------------- >< 


For more information, see SendMessageToltem. 
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The ooDialog framework provides a number of utility classes that are useful when writing more complex 


programs. These classes do not easily fit into the category of a type of dialog or a type of dialog control 


and are therefore documented separately. In addition ooDialog places some globally available objects in 


the .1ocal envirnoment. 


The classes and objects in the following table are described in this chapter: 


Table 10-1. ooDialog Utilitiy Classes and Objects 
































Utility Class or Object Description 
.SystemErrorCode .SystemErrorCode 
DlgArea Class DlgArea Class 
DlgAreaU Class DlgAreaU Class 
DIgUtil Class DIgUtil Class 

Point Class Point Class 

Rect Class Rect Class 

Size Class Size Class 
VirtualKeyCodes Class VirtualKeyCodes Class 











10.1. .SystemErrorCode 


The .SystemErrorCode can be used, at times, to obtain additional information when the invocation of a 
method generates an operating system error. 


ooDialog provides an interface to the Windows operating system APIs. To be specific, the Win32 APIs, 
and mostly those dealing with dialogs and other graphical aspects of the user interface. Some of the 
Win32 APIs will set a system error code when something goes wrong. (On the other hand, many of the 
Win32 APIs do not set a system error code.) 


When the ooDialog framework first intializes, it sets the value of .SystemErrorCode to 0. Some, of the 
methods of the ooDialog classes will set the .SystemErrorCode to the value of the system error code 
when the method detects that a Win32 API has failed and has set the error code. Most methods do not 
change the value of .SystemErrorCode. Only those methods that explicitly document they use 
.SystemErrorCode will ever change its value. 


One consequence of the fact that most methods do not change .SystemErrorCode is that its value is only 
meaningful immediately after the invocation of a method that is documented as using .SystemErrorCode. 
Those methods will set the code to 0 and, if they detect a Win32 API has set the system error code to 
non-zero, they will then set .SystemErrorCode to the value of the system error. Checking 
.SystemErrorCode after the invocation of a method that does not set .SystemErrorCode will tell the 
programmer nothing. Neither that a system error happened, or that it did not happen. 
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The getImage() method of the .Image class is one method that does change .SystemErrorCode. This is an 


example of a possible usage: 


image = .Image~getImage("resources\bogus. bmp") 


if image~isNull then do 


say "Error getting the bogus.bmp image." 
if .SystemErrorCode <> 0 then do 


say ’System error code:? .SystemErrorCode 
say ’ system message:’ SysGetErrorText (.SystemErrorCode) 
end 
end 
/* 


Output on the screen might be: 


Error getting the bogus.bmp image. 


System error code: 2 


system message: The system cannot find the file specified. 


*/ 


10.2. DigUtil Class 


All the methods of the DlgUitl class are class methods. There are no instance methods, other than 
inherited methods, for this class. The class methods are a collection of common utilities, mostly for 


converting different Windows values, getting version information, and the like. 


Requires: 


The DlgUtil class requires the class definition file oodPlain.cls: 


::requires "oodPlain.cls" 


Methods: 


The class methods of DlgUtil are listed in the following table: 


Table 10-2. Methods of the DigUtil class 






































Method... ... description 
colorRef (Class Method) colorRef 
comCtl32Version (Class Method) comCtl32Version 
getB Value (Class Method) getB Value 
getGValue (Class Method) getGValue 
getRValue (Class Method) getRValue 
getSystemMetrics (Class Method) getSystemMetrics 
hiWord (Class Method) hiWord 

loWord (Class Method) loWord 

or (Class Method) or 
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Method... .-description 
and (Class Method) and 
version (Class Method) version 





10.2.1. version (Class Method) 


+-Full----+ 
»»-.DlgUtil^version(-------------- )------------------------ >< 


Returns the ooDialog version string. 


Arguments: 


There are no arguments for this method. 


format 


A keyword indicating the format of the returned version string. Only the first letter is needed 
and case is not significant. Any unrecognized keyword is ignored and the default format is 
used. The format for each keyword is as follows: 


Full 


A string specifying the version of ooDialog. This is the default. The string has the format: 
ooDialog Version x.x.x.SS (an ooRexx Windows Extension) where x.x.x is the 
ooRexx interpreter version and SS is the Subversion revision number of the build. The 
actual version string might look like: ooDialog Version 4.0.0.3734 (an ooRexx 


Windows Extension) 


Short 


Only the x.x.x.SS part of the full version string is returned. 


Return value: 
A string in one of the formats specified above. 
Example: 
у = .DlgUtil” version 
say у 
say 
if .DlgUtil^version("SHORT") < 4.1.0.0000 then do 


say ’Too bad, you are still running ooRexx 4.0.0’ 
end 
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else do 
say ’Great you have upgraded past ooRexx 4.1.0’ 
end 
::requires ’oodPlain.cls’ 
/* On the screen you might see: 
ooDialog Version 4.0.0.3768 (an ooRexx Windows Extension) 


Too bad, you are still running ooRexx 4.0.0 


*/ 


10.2.2. comCtl32Version (Class Method) 


»»-.DlgUtil^comCtl32Version(-------------- )---------------- >< 
+-Number--+ 
+-08------ + 
+-Еш1----+ 


Use this method to determine Ше version of Ше Common Controls Library used by ooDialog on Ше 
current system. 


Arguments: 


The single argument is: 


format 


A keyword indicating the format of the returned version string. Only the first letter is needed 
and case is not significant. Any unrecognized keyword is ignored and the default format is 
used. The format for each keyword is as follows: 


Short 


The version number, for instance 4.72 or 6.0. This is the default. 


Number 


This is an alias for short. 


OS 


The minimum operating system that can be expected to be compatible with the libray. 
Earlier versions of the common control library were also distributed with Internet 
Explorer and so an OS part of say, W98 / IE 4.01 would indicate that the current 
common control library supports all the features available on Windows 98 or with Internet 
Explorer 4.01. 
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Full 


The full format string in the format comct132.d11 version 6.0 (XP). Where the 6.0 is 
the number part and XP is the OS part. 


Return value: 


This method returns a string in one of the formats described above. 


Example: 


In the following example, the programmer repositions the dialog controls under certain conditions. 
In Windows XP and later, this task is more accurate if the getIdealSize() method of the 
ButtonControl class is used. However, the programmer needs the application to also run on 
Windows 2000. He uses the comCt132Version() method to determine if the getIdealSize method is 
available. If it is not available he uses an alternative, but less accurate method to reposition the 
controls. 


::method repositionControls 
if .DlgUtil^comCtl32Version < 6.0 then return self^doW2KReposition 


size = self^getButtonControl(IDC. CHECK TWO)^getIdealSize 
if size == .nil then return .false 


-- do the repositioning 


return .true 
An alternative way to achieve the same thing might be: 


::method repositionControls 
if .DlgUtil^comCtl32Version(?0?) == "XP" then return self^doXPReposition 


-- Do the less accurate repositioning 


return .true 


10.2.3. loWord (Class Method) 


»»-.D1gUtil^loWord(--param--)------------------------------ >< 


The Windows API often packs two values into a single number. One value in the low-order word and the 
other value in the high-order word. In ooDialog this is most often seen in the arguments passed to event 
notification methods. This utility method is used to extract the low-order word from a number. 
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Arguments: 


The arguments are: 


param 


The number whose low-order word is needed. 


Return value: 


The return is the low-order word portion of the number. 


Example: 


A common place in the Windows API where two values are packed into a single number is where 
the API deals with position. This example shows how to extract the x and y position coordinates of 
a dialog after it has been moved. The example is complete, it can be cut and pasted into a file and 
will execute as is. 

dlg = .MovingDialog^new 

dlg~createCenter(100, 60, "Move Me") 

dlg^execute("SHOWTOP") 


::requires ’ooDialog.cls’ 
::class ’MovingDialog’ subclass UserDialog 


::method init 
forward class (super) continue 


self^connectMove (onMove) 


::method onMove 
use arg unUsed, posInfo 


-- Look at our message queue to see if the next message in the queue is also 
-- onMove. If so, just return. 

msg = self^peekDialogMessage 

if msg^left(6) - "ONMOVE" then return 


-- Now, we should be done moving, print out where we are. 


x = .DlgUtil^loWord(posInfo) 
y = .DlgUtil^hiWord(posInfo) 
say ’At coordinate (? x^," y? ) on the screen. (In pixels.)? 


10.2.4. hiWord (Class Method) 
»»-.DlgUtil^hiWord(--param--)------------------------------ >< 


The Windows API often packs two values into a single number. One value in the low-order word and the 
other value in the high-order word. In ooDialog this is most often seen in the arguments passed to event 
notification methods. This utility method is used to extract the high-order word from a number. 


406 ooRexx OODialog Reference Version 4.0.0 


Chapter 10. Utility Classes and Objects 


Arguments: 


The arguments are: 


param 


The number whose high-order word is needed. 


Return value: 


The return is the high-order word portion of the number. 


Example: 


See the loWord() example. 


10.2.5. or (Class Method) 


»»--.DlgUtil^or(----number--4--)----------------------------------- >< 


Combines any number of numerical values into a single number by oring the individual numbers 
together. This is the typical or operation used by assembly and C programmer’s. The ooDialog 
programmer does not need to understand the concept to use this method. Some arguments to some 
methods in the ooDialog framework can take a value that is a combination of some individual flags. The 
or method is provided to construct this combination. 


Details: 


Raises syntax errors when incorrect arguments are detected. 


Arguments: 


There is no restriction on the number of arguments to this method, other than each argument must 
represent a whole number. 


As a convenience, the whole numbers can also be specified as a string with the following format: 0x 
followed by a series of hexidecimal digits with no spaces. Such as "Oxff12abc9" or "0x1" or 
"0x00000080". This makes it easy to look up and use the value of a flag directly. For instance 
looking up the value of ILC_COLOR24, one would see it is 0x00000018. This value could be used 
directly in the or() method. Case is not significant in the string. 


Return value: 


The return value is a number that is the result of combining all the individual arguments together. 


Example: 


One method that has an argument that can be the result of combining a number of flags is the 
create() method of the .ImageList class. This is how the or method might be used 


flags = .DlgUtil^or(.Image^toID(ILC COLOR24), .Image^toID(ILC MASK)) 
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-- Create an empty .ImageList object: 
imageList = .ImageList^create(.Size^new(61, 46), flags, 10, 10); 
The following is equivalent to the above example: 


flags = .DlgUtil^or(0x00000018, 0x00000001) 

-- Create an empty .ImageList object: 

imageList = .ImageList^create(.Size^new(61, 46), flags, 10, 10); 
To round out the examples a little: 


flags = .DlgUtil^or(.Image^toID(ILC COLOR24), .Image^toID(ILC MASK)) 
say "Flags value:" flags 


flags = .DlgUtil~or(0x00000018, 0x00000001) 
say "Flags value:" flags 


::requires ’oodDialog.cls’ 
/* Output would be: 


Flags value: 25 
Flags value: 25 
*/ 


10.2.6. and (Class Method) 


»»--.DlgUtil^and(--numberi-,-number2--)---------------------------- >< 


Combines two numbers into a single number by anding the individual numbers together. This is the 
typical and operation used by assembly and C programmer’s. The typical ooDialog programmer would 
have no need of the method. It is provided as a convenience for use in sophisticated ooDialog programs. 


The normal use of an and operation in ooDialog programs is to extract the low or high words from an 
argument returned from the operating system. The addition of the loWord() and hiWord() methods to the 
ooDialog framework have eliminated the reason for this usage. 


Details: 


Raises syntax errors when incorrect arguments are detected. 


Arguments: 
The required two arguments are the whole numbers to be anded together. 


As a convenience, the whole numbers can also be specified as a string with the following format: Ох 
followed by a series of hexidecimal digits with no spaces. Such as "Oxff12abc9" or "0x1" or 
"0x00000080". 


Return value: 


The return value is the number that is the result of anding the two arguments together. 
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Example: 


The following example is part of a generic method in an application that returns the text of an edit 
control. The application is a complex one and has many edit controls that are read only. The text for 
read only controls is ignored. The method returns .nil for read only controls to differentiate the 
difference between a read only control and a control that has the empty string. 


The value of the ES_READONLY style is 0x0800. 
::method getEditText private 


use strict arg control 


-- If the control is read only, we just return .nil 
if .DlgUtil^and(control^getStyleRaw, 0x0800) <> 0 then return .nil 


10.2.7. getSystemMetrics (Class Method) 
»»--.DlgUtil^GetSystemMetrics(--index--)----------------------- >< 


Obtains the system metric value for the given index. 


Arguments: 


The only argument is: 


index 
The numeric index of the system metric. 


Good documentation on the system metrics is found in the MSDN Library under the 
GetSystemMetrics function. This documentation contains both the numeric value of the 
different indexes and information on what is returned for each index. The documentation is 
easy to found using a Google search of "GetSystemMetrics MSDN library" 


Return value: 


The return value is dependent on the index queried. Consult the MSDN library for information on 
the returned values. 


Note: The OS will return 0 if an invalid index is used. Hoever, the return value for some indexes is 
also 0. The programmer will need to determine from the context if 0 is an error return or not. 


Example: 


The following code snippet is from an application where the user can have 5, 6, or more, 
independent dialogs open at one time. One of the menu options is "Tile Dialogs." When the user 
selects this option all the open dialogs are "tiled." 
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All the open dialog objects are stored in a queue. In the onTile method, which is invoked when the 
user selects the menu item, each dialog is fetched in turn from the queue. Then the dialog is 
repositioned at an offset from the preceding dialog. It is shifted to the right the width of 2 scroll bars 
and shifted down the the width of the title bar. (This width is the title bar width plus the thin border 
around the title bar.) The height of the thin border, the height of the title bar, and the width of a 
scroll bar are all determined by querying the system metrics. 


::method onTile 
expose offSetX offSetY dialogQueue 
-- SM_CXVSCROLL = 20 
-- SM_CYCAPTION = 4 
-- SM_CYBORDER = 6 


if \ offSetX*datatype(’W’) then do 
scrollBarX = .DlgUtil^getSystemMetrics(20) 
titleBarY = .DlgUtil~getSystemMetrics (4) 
windowBorderY = .DlgUtil~getSystemMetrics (6) 


offSetX = 2 * scrollBarX 
offSetY = (2 * windowBorderY) + titleBarY 


end 


parse value self^getWindowRect(self^dlgHandle) with ху. 


do dlg 
x += 


y += 


self~ 


end 


10.3. Rect Class 


over dialogQueue 
offSetX 
offSetY 


setWindowRect(dlg^dlgHandle, x, y, O, O, "NOSIZE") 


The Rect object is most often used to represent a rectangle on a coordinate system, specifically the 
coordinate system used by Windows where the upper left corner is considered (0,0). However, it is 
convenient to use the Rect object for other things, for instance the margin around a rectangle. 


Requires: 


The Rect class requires the class definition file oodPlain.cls: 


::requires "oodPlain.cls" 
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Methods: 


Instances of the Rect class implement the methods listed in the following table: 


Table 10-3. Rect Instance Methods 



































Method... ..оп page 
new (Class Method) new 
bottom bottom 
bottom- bottom= 
left left 

left= left= 

right right 
right= right= 

top top 

top= top= 











10.3.1. new (Class Method) 


*-0----* +-left-+ +-left--+ *-left---* 
»»-aRect^new(--4------ *--,--4------ *--,--4------- *--,--—4-------- *--)------ >< 
+-left-+ +-top--+ +-right-+ +-bottom-+ 


Instantiates a new Rect object. All the arguments are whole numbers. 


Arguments: 


The arguments are: 
left 
The left postion. The default is 0. 


top 

The top position. The default is the value of left. 
right 

The right position. The default is the value of left. 
bottom 


The bottom position. The default is the value of left. 


Return value: 


The new Rect object is returned. 
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Example: 


r = .Rect^new(3, 4, 13, 9) 

say "Upper corner (’r~left’,’r~top’) lower corner ’r~right’,’r~bottom’)’ 
say 

margin = .Rect^new(5) 

say ’Margins:’ 

say ’ Left: " margin left 


say ’ Top ? margin top 
say ? Right " margin right 
say ? Bottom? margin bottom 
say 

r^left - 55 

r^top = 75 


r^right - 110 

r^bottom - 125 

say ? Мен upper corner (’r~left’,’r~top’) new lower corner ’r~right’,’r~bottom’)’ 
say 


/* Output would be: 
Upper corner (3,4) lower corner 13,9) 


Margins: 
Left: 5 
Top 5 
Right 5 
Bottom 5 


New upper corner (55,75) new lower corner 110,125) 


/ж 


10.3.2. left 


SS -eReCt Lei ta a Se >< 
Retrieves the left value of the rectangle. 
Arguments: 

This method takes no arguments 


Return value: 


The return value is the numeric value for the left of the rectangle. 


Example: 


See .Rect~new example. 
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10.3.3. left= 
»»-aRect^left-value---------------------------------------- >< 
Sets the left value of the rectangle. 


Arguments: 


This has one argument: 


value 


The left value for the rectangle. 
Return value: 
This method does not return a value. 


Example: 


See .Rect~new example. 


10.3.4. top 


2»-aRéct Ops aaa S SSS ss SSS SS Sa SSS SSS SS SSS Se esas >< 
Retrieves the top value of the rectangle. 
Arguments: 

This method takes no arguments 


Return value: 


The return value is the numeric value for the top of the rectangle. 


Example: 


See .Rect~new example. 


10.3.5. top= 


2»-aRect Бор-утайне------------------------ -- >< 


Sets Ше top value of Ше rectangle. 
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Arguments: 


This method takes one argument: 


value 


The top value for the rectangle. 
Return value: 
This method does not return any value. 


Example: 


See .Rect~new example. 


10.3.6. right 
»»-ahect right---------------------c-cccccceccosenococeToc mE >< 
Retrieves the right value of the rectangle. 
Arguments: 
This method takes no arguments 


Return value: 


The return value is the numeric value for the right of the rectangle. 


Example: 


See .Rect~new example. 


10.3.7. right= 


2»-aRect кїрһ=уагце============_= = зеш ы ыы SS >< 


Sets the right value of the rectangle. 


Arguments: 


This method has one argument: 


value 


The new right value for the rectangle. 


Return value: 


There is nor return value for this method. 
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Example: 


See .Rect~new example. 


10.3.8. bottom 


22-aRéct Боввош----------------------<+-- -- >< 
Retrieves Ше bottom value of Ше rectangle. 
Arguments: 

This method takes no arguments 


Return value: 


The return value is the numeric value for the bottom of the rectangle. 


Example: 


See .Rect~new example. 


10.3.9. bottom= 


>>-аКесв”БоБошеталне-------------------------- -- >< 


Sets the bottom value of Ше rectangle. 


Arguments: 


This method has one argument: 


value 


The bottom value for the rectangle. 


Return value: 


The method does not return a value. 


Example: 


See .Rect~new example. 


10.4. Point Class 


The Point class represents a point in a 2-D coordinate system. 
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Requires: 
The Point class requires the class definition file oodPlain.cls: 


::requires "oodPlain.cls" 


Methods: 


Instances of the Point class implement the methods listed in the following table: 


Table 10-4. Point Class and Instance Methods 























Method... ..оп page 
new (Class Method) new 

x x 

х= х= 

y y 

y y= 











10.4.1. new (Class Method) 


+-0-+ +-х-+ 
>>-.Роїпї^пем(--+---+--,--+---+--)------------------------- >< 
+-х-+ +=у=+ 


Arguments: 


The arguments are: 


The x coordinate of the point. The default is 0. 


The y coordinate of the point. The default is the x coordinate. 


Return value: 


This method returns a new Point object. 


Example: 


р = .Point^new(45, 90) 

say ’Point p is at (Cp^x?,?p^y?)? 

say 

q = .Point~new(55) 

say ’A new point q is at (Фа х?,?ау?)? 
say 
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ах = 150 

ау = 300 

say 'Changed point q to be at (?q^x?,?q^y?)? 
say 

::requires ’oodPlain.cls’ 

/* Output would be: 

Point p is at (45,90) 

А new point д is at (55,55) 


Changed point q to be at (150,300) 


*/ 


10.4.2. x 


22-8POXnL Rees Sse eS Se SSS a SS SSS SS SSS SSeS SSeS Seas >< 
Retrieves the x coordinate of the point. 
Arguments: 

This method takes no arguments 


Return value: 


The return value is the x coordinate. 


Example: 


See .Point~new example. 


10.4.3. x= 


2»-aPoisnt х-утайче----------------- -<-<--- >< 


Sets Ше x coordinate of the point 


Arguments: 


This method has one argument: 


value 


The new x coordinate for the point. 
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Return value: 


This method does not return a value. 


Example: 


See .Point~new example. 


10.4.4. у 
>>=аРроїпЬ yess eases SSS SSS SSS Sa Sa emere eiie >< 
Retrieves the y coordinate of the point. 
Arguments: 
This method takes no arguments 


Return value: 


The return value is the y coordinate of the point. 


Example: 


See .Point~new example. 


10.4.5. y= 


>> -аРоппЬ у-таше------------- << SSeS >< 
Sets Ше у coordinate of the point 


Arguments: 


This method has one argument: 


value 


The new y coordinate for the point. 
Return value: 
This method does not return a value. 


Example: 


See .Point~new example. 
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10.5. Size Class 


A Size object encapsulates a width and height dimension in a 2-D coordinate system. 


Requires: 
The Size class requires the class definition file oodPlain.cls: 


::requires "oodPlain.cls" 


Methods: 


Instances of the Size class implement the methods listed in the following table: 


Table 10-5. Size Class and Instance Methods 


























Method... ..оп page 
new (Class Method) new 

width width 
width- width= 
height height 
height= height= 








10.5.1. new (Class Method) 


+-0----- + +-width---+ 
>>-.Size~new(--+------- +--,--+--------- +--)---------------- >< 
+-width-+ +-height--+ 


Instantiates a new Size object with the dimensions specified. 


Arguments: 


The arguments are: 


width 


The whole number value of the width of the new object. The defualt is 0. 


height 


The whole number value of the height for the new object. The default is the width value. 


Return value: 


This method returns the new Size object. 
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Example: 


size = .Size~new(4, 8) 

say ’Width:’ size^width ’Height:’ size^height 
say 

size2 = .Size^new(16) 

say 'А new size object:’ 

say ? Width: " size2^width 

say ? Height:" size2^ height 

say 


size2^width - 100 
size2^height - 300 
say "New width:’ size2^width "new height: size2^ height 
say 
::requires ’oodPlain.cls’ 
/* Output would be: 
Width: 4 Height: 8 
А new size object: 
Width: 16 
Height: 16 


New width: 100 new height: 300 


*/ 


10.5.2. width 


22-8D0Ize width---------—--————--c--c SSS eS Seas Seas >< 
Retrieves the width of the size object. 
Arguments: 

This method takes no arguments 


Return value: 


The return value is the width of the object 


Example: 


See .Size~new example. 
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10.5.3. width= 
»»-aSize^width-value--------------------------------------- >< 
Sets the width of the size object. 


Arguments: 


This method has one argument: 


value 


The new width of the size object. 
Return value: 
This method does not return a value. 


Example: 


See .Size~new example. 


10.5.4. height 
2»-8Dize height----—---—----—-—-----------0cc eee >< 
Retrieves the height of the size object. 
Arguments: 
This method takes no arguments 


Return value: 


Returns the height of the size object. 


Example: 


See .Size~new example. 


10.5.5. height= 


2»-aDize Непрв-тапе---------------------- -- >< 


Sets Ше height of the size object. 
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Arguments: 


This method has one argument: 


value 


The new height of the size object. 
Return value: 
This method does not return a value. 


Example: 


See .Size~new example. 


10.6. DigArea Class 


The DlgArea class provides assistance in laying out the dialog controls in a dynamically defined dialog. 
The class defines an area of a UserDialog and provides coordinates of and within it. It is a helper for the 
DefineDialog Method of an OODialog UserDialog Object and has no effect on any Windows Object. 


To use objects of the DlgArea class include this line in your code: 
::requires "OODIALOG.CLS" 


The following figure shows the measuement attributes used to position a DlgArea on a UserDialog. 
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Figure 10-1. DigArea Measurements 


UserDialog 





10.6.1. Init 


>>- aDlgArea"Init(--X--,--Y--,--Width--,--Height--*------------- +--)-->< 
+--,--Margin--+ 


Arguments: 
The arguments you pass to the new method when creating a DlgArea Object are: 


X 


The X coordinate in dialog units relative to the UserDialog of the top left corner of the area 
you wish to define 


The Y coordinate in dialog units relative to the UserDialog of the top left corner of the area 
you wish to define. 
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Width 


The width in dialog units of the area of the UserDialog you wish to define 


Height 


The height in dialog units of the area of the UserDialog you wish to define 


Margin 
An inner margin within the DlgArea in Dialog Units to be left blank. The default is 5 


Example: 


u = .dlgArea^new(0, 0, self^SizeX,Self^SizeY) /* u is whole of UserDialog */ 
b = .digArea^new(u^x("704"), u^y , u^w("R"), u^h("R")) /* sub area for buttons */ 


10.6.2. B 


Returns the y coordinate of the bottom margin in dialog units relative to UserDialog. 


22--ADIEArea В--- отнет ste >< 


10.6.3. Bottom 


Returns the y coordinate of the bottom edge in dialog units relative to UserDialog. 


>2- ADL EAT Ea Bottón se sega >< 


10.6.4. CX 


Synonym for the W method. 

>>--АП ра Агеа сх(--+------- 4--)---------------------------------------- >< 
+--1/---+ 
+-- "RU --+ 


10.6.5. СҮ 


Synonym for the Н method. 

»»--ADlgArea^cy(--*------- 4--)---------------------------------------- >< 
+--1/---+ 
+-- "RU --+ 
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10.6.6. H 


Returns a height in dialog units relative to the dialog area. 


If no argument is passed returns the inter-margin height. 


»»--ADlgArea^h(--*------- +--)----------------------------------------- >< 
+--1/у---+ 
+-- "R'---a 

Arguments: 


The arguments you pass to the H method are: 


n% 


If n is a percentage returns n% of the inter-margin height. 


"R" 


If "R" is passed returns Remaining height between last ~y and bottom margin. 


10.6.7. HR 


Returns the remaining height between last ~Y and bottom margin in dialog units. This is equivalent to 
~H("R"). 


>>--АПрАгеа"нг--------9---------------------<4--- = ш зене шнш ән ет >< 


10.6.8. L 


Returns the x coordinate of the left margin in dialog units relative to UserDialog. 


s»--ADIlgAréa Laast sas SoS Ss SSS SSS ee Sere cesar asssraasesase= >< 


10.6.9. Left 


Returns the x coordinate of the left edge in dialog units relative to UserDialog. 


s»-cADIgArea Left=ssas sos Ss SSS rsa Ses SS SSS Ser ts <<< 9 з39ча 9 >< 


10.6.10. Margin 


Size in dialog units of DlgArea margin. 
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>>> AD eArea Мавраа--------т----- Sse >< 


10.6.11. R 


Returns the x coordinate of the right margin in dialog units relative to UserDialog. 


22 --АШрАдгеав-------- 559 eS >< 


10.6.12. Right 


Returns the x coordinate of the right edge in dialog units relative to UserDialog. 


22> TAD BAe a Right se So >< 


10.6.13. T 


Returns the y coordinate of the top margin in dialog units relative to UserDialog. 


22cCCADIBAreas 1------- a ciem >< 


10.6.14. Тор 


Returns the y coordinate of the top edge in dialog units relative to UserDialog. 


>52--АрІБАгеа”Тор--===---==-=--=---==-===-------==-----==-------=-5---5-5 >< 


10.6.15. W 


Returns a width in dialog units relative to the dialog area. 


If no argument is passed returns the inter-margin width. 


»»--ADlgArea^w(--*------- Se a as tat a А >< 
r--nÁ---* 
+-- "R"--+ 
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Arguments: 


The arguments you pass to the Y method are: 
n% 
If n is a percentage returns n% of the inter-margin width. 


"R" 


If "R" is passed returns Remaining width between last ~x and right margin. 


10.6.16. WR 


Returns the remaining width between last ~X and right margin in dialog units. This is equivalent to 
~W("R"). 


2»--CADIgArea иг--3-----------<<+------------4---+<---<--<<4+<----<+-<++--- >< 


10.6.17. X 


Returns an X Coordinate in dialog units relative to the dialog area. 


If no n is passed returns the x coordinate of the left margin. 


»»--ADlgArea^x(--4*------ *--)------------------------------------------ >< 
+--п---+ 
+--пў--+ 

Arguments: 


The arguments you pass to the X method are: 


n 
If n is passed and is positive, then returns the x coordinate n dialog units to the right of the left 
margin. If n is passed and is negative, then returns the x coordinate n dialog units to the left of 
the right margin.. 

n% 


If n is passed and is a percentage, then returns the x coordinate n% of the way between the left 
and right margins. 


10.6.18. Y 


Returns an Y Coordinate in dialog units relative to the dialog area. 
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If no n is passed returns the x coordinate of the top margin. 


»»--ADlgArea^y(--*------ *--)------------------------------------------ >< 
+--п---+ 
+--1/у--+ 

Arguments: 


The arguments you pass to the Y method are: 


n 
If n is passed and is positive, then returns the y coordinate n dialog units below the topmargin. 
If n is passed and is negative, then returns the y coordinate n dialog units above the bottom 
margin.. 

n% 


If n is passed and is a percentage, then returns the y coordinate n% of the way between the top 


and bottom margins. 


10.6.19. DigArea Example 


On a UserDialog we want the top left to be an entry area, with an area for buttons on the right and a 
status area below. 

We decide to give 7096 of the width and 90% of the height to the entry area. We leave the margin as the 
default. We want all the areas to resize themselves if we change the UserDialog size except ће OK 
button should remain 15 units high. 


Figure 10-2. DlgArea Plan 





Entry Buttons 











Status 





Here is what our DefineDialog method might look like: 


Иж ------------------------------------------------------------------------- */ 
: : method DefineDialog 


426 ooRexx OODialog Reference Version 4.0.0 


Chapter 10. Utility Classes and Objects 


Иж ------------------------------------------------------------------------- */ 
/* define DlgArea named u as whole of user dialog ж/ 
u-.dlgArea^new( 0 3 O,self^SizeX,Self^SizeY) /* whole dig  */ 
/* define DlgArea named e within DlgArea u for entry line ж/ 
e-.dlgArea^new(u^x ,u^y ,u^w(' 704") ,u~h("90%") ) 


/* define DlgArea named s within DlgArea u for Status Area in remaining height*/ 








s-.dlgArea^new(u^x ,u^y(C'904") ,u^w(" 704") ,u^hr ) 
/* define DlgArea named b within DlgArea u for Button area */ 
b=.dlgArea~new(u~x("70%") ,u7y ,u^wr ,u^hr ) 
/* entry line coterminous with area e margins */ 


self^addEntryLine(12,"text",e^x,e^y,e^w,e^h, "multiline") 


/* Status Area Coterminous with area s margins ж/ 
self^addText(s^x,s^y,s^w,s^h,"Status info appears here", ,11) 


/* Seven buttons evenly spaced at 10% intervals, 9% high ж/ 
do i = 0 to 6 

self^addButton(12*i,b^x,b^y((i ж 10) |1 "/") ъъ, ЪЪ ("9%"), "Button" i,"Button"| |i) 
епа /* DO */ 


/* ok button 15 dialog units high at bottom of area b */ 
self^addButton(1,b^x,b^y(-15),b^w,15, "ОК", "OK", "Default") 


Here is the resultant dialog. 
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Figure 10-3. Sample DigArea 
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10.7. DIgAreaU Class 


The DIgAreaU class is a subclass of the DlgArea class that assists the creation of dynamically resizable 
Dialogs. This class provides assistance in resizing and / or positioning controls when a dialog is resized. 
When the DlgArea and DlgAreaU classes are used together, the they provide a convenient way to create 
resizable dialogs. 


To use objects of Ше DlgAreaU class include this line in your code: 


::requires "OODIALOG.CLS" 


10.7.1. Init 


>>- aDlgAreaU^Init (Dialog--4-------------------------- +-------- +-)-->< 
+-- ,--Магріп-+ | | 
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+--,--------- +--,-NoResize-+ | 
Фе, ========= +------------ +-NoMove-+ 


The DIgAreaU object creates a dialog area coterminous with the calling dialog. It inherits all the 
methods and attributes of the DlgArea Class (listed above). 


Arguments: 


The arguments you pass to the new method when creating a DlgArea Object are: 
Dialog 

An Object that is SubClassed from A UserDialog. 
Margin 

See DigArea Margin. 


NoResize 


A set of Dialog Ids of widgets not to be resized during a resize. 


NoMove 


A set of Dialog Ids of widgets not to be moved during a resize. 


10.7.2. CorrectionFactor 


2»--ADIgAreaU CorrectionFactor--------c2------2--c----o2ccHenr-ccenenormou >< 


An attribute containing the value used to adjust the ratio of the top & left margins to the bottom & right 
margins. (The default correction factor is set to 1.05.) See the Possible Problems section for some 
additional detail. 


10.7.3. LastError 
22--ADIspAreaU Last rio pe as se as aS SS SSS >< 


An attribute holding the details if an error was encountered when parsing the calling dialog’s 
DefineDialog method. The value of the attribute is .nil if no error occurred. 


10.7.4. NoMove 
22--ADIpAreaU НоМоте-<+--<--------<---<+-------<-< <<< --<-<----- >< 


An attribute holding Ше set of Dialog Ids of widgets not to be moved during a resize event. 
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10.7.5. NoResize 


22--ADIgAreaU NOR6SIZ6 Ss res eset assess >< 


An attribute holding the set of Dialog Ids of widgets not to be resized during a resize event. 


10.7.6. Creating Resizeable Dialogs 


You can use Ше DlgAreaU Object to facilitate in creating dynamically resizable Dialog objects, but to do 
so you must carefully satisfy all the requirements below. 


The Dialog must be created with the ThickFrame option. It may be created with the UserDialog Create 
method or CreateCenter method. 


Your Dialog init method must include the line: 
self~connectResize("OnResize") 
Your DefineDialog method must start with these lines: 


expose u 
u = .dlgAreaU^new(self) /* whole dig  */ 


Your DefineDialog method must not reference variables within the Add Method parameters, although 
you can use references to DlgArea attributes, so 


Self^addButton(23,1,5,6,"MyButton","Pressed") 
self^addButton(14,b^x,b^y ("104") ,b^w,b^h("94"),"Button" 1,"Button"||1) 


Both are OK, whereas 
/* Seven buttons evenly spaced at 10% intervals, 9% high */ 
do i = 0 to 6 
self^addButton(12*i,b^x,b^y((i ж 10)||"A"),b^w,b^h("94"),"Button" і, "Button"| |i) 
end /* DO */ 


would now fail as the variable i is referenced within the parameters. 


To debug your DlgAreaU call/insert the following after the instantiation 


if u^lastError \= .nil then call errorDialog u^lastError 


You must also include the following in your code. 


[x ------------------------------------------------------------------------- */ 
::method OnResize 

Иж ------------------------------------------------------------------------- */ 
expose u 


if u^lastError \= .nil then call errorDialog u^lastError 
use arg dummy,sizeinfo 

/* wait for last size event msg then resize */ 
if self^PeekDialogMessage^left(8) \= "OnResize" then u^resize(self,sizeinfo) 
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The DlgAreaU method will then automatically resize & place the following widgets in your dialog when 
the dialog frame is dragged or the minimize, maximise or restore buttons are pressed: 


Table 10-6. DigAreaU Automatic Resize Elements 
































BLACKFRAME BLACKRECT BITMAPBUTTON BUTTON 
CHECKBOX COMBOBOX ENTRYLINE GRAYFRAME 
GRAYRECT GROUPBOX LISTBOX LISTCONTROL 
PASSWORDLINE PROGRESSBAR RADIOBUTTON SCROLLBAR 
SLIDERCONTROL TABCONTROL TEXT TREECONTROL 
WHITEFRAME WHITERECT 





The following widgets can be defined in a UserDialog, but cannot be handled by Ше DlgAreaU resize 
method, so should not be used. 


Table 10-7. DigAreaU Non-Automatic Resize Elements 























BUTTONGROUP CHECKBOXSTEM CHECKGROUP COMBOINPUT 
FULLSEQ INPUT INPUTGROUP INPUTSTEM 
OKCANCEL.... RADIOGROUP RADIOSTEM 





All of these widgets can be achieved using combinations of the permitted methods. 


10.7.7. Possible Problems 


The DigAreaU resize method can create slightly over-size margins on the left & bottom of the Dialog. To 
correct for this Ше DlgAreaU class has a CorrectionFactor attribute set by default to 1.05. In tests, this 
correction factor appears to neutralise the effect. If your dialogs have over (or under) sized margins, you 
may be able to correct this in your code by adjusting the Correction Factor. For example: 


U-.DlgAreaU^new(self) 


U^CorrectionFactor-1.07 


You will have to experiment to find the apropriate setting for this attribute. 


10.7.8. Sample Code 


/* DlgAreaDemo.Rex -- 


MyD1g-.MyDialog^new 


Demonstrate DlgArea & DlgAreaU Classes 


MyDlg^execute("ShowTop") 


MyDlg~DeInstall 


exit 


::requires "OODWINS32.CLS" 
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::class MyDialog Subclass UserDialog 


/ж ============ш=ш=шш=шшшшшшшшш шшш шш шш шш шшш шш шшш шшш шшш Ж/ 
::method Init 
Иж ------------------------------------------------------------------------- */ 
self~Init:super 
rc-self^CreateCenter(250,250,"MyDialog","ThickFrame", ,"MS Sans Serif",8) 


self ~InitCode=(rc=0) 
self~connectResize("OnResize") 


Иж ------------------------------------------------------------------------- */ 
::method DefineDialog 

Иж ------------------------------------------------------------------------- */ 
expose п 

u=.dlgAreaU~new (self) /* whole dig */ 
if u^lastError \= .nil then call errorDialog u^lastError 

e-.dlgArea^new(u^x ,u^y u^ w(' 704") ,u~h("90%") ) /* edit area */ 
s-.dlgArea^new(u^x ,u^y(C' 904") ,u^w(" 704") ,u^hr ) /* status area */ 
b=.dlgArea~new(u~x("70%") чу ,u^wr ,u^hr ) /* button area */ 


self^addEntryLine(12,"text",e^x,e^y,e^w,e^h, "multiline") 
self^addText(s^x,s^y,s^w,s^h,"Status info appears here", ,11) 


self^addButton(13,b^x,b^y ("004") ,b^w,b^h("94"),"Button" 0,"Button"| |0) 
self^addButton(14,b^x,b^y ("104") ,b~w,b~h("9%") , "Button" 1,"Button"||1) 
self^addButton(15,b^x,b^y ("204") ,b^w,b^h("94"),"Button" 2,"Button"||2) 
self^addButton(16,b^x,b^y ("304") ,b^w,b^h("94"),"Button" 3,"Button"| |3) 
self^addButton(17,b^x,b^y("404"),b^w,b^h("94"),"Button" 4,"Button"||4) 
self^addButton(18,b^x,b^y ("504") ,b~w,b~h("9%") , "Button" 5,"Button"||5) 
self^addButton(19,b^x,b^y ("60/4") ,b^w,b^h("94"),"Button" 6,"Button"||6) 
self^addButton( 1,b~x,b~y("90%") ,b~w, b™h("9%") , "Ок", "Ок", " DEFAULT") 





Иж ------------------------------------------------------------------------- */ 
::method Unknown 

Иж ------------------------------------------------------------------------- */ 
use arg msgname, args 

StatusLine = Self~GetStaticControl(11) 

StatusLine^SetTitle("You Pressed" msgname) 


Иж ------------------------------------------------------------------------- */ 
::method OnResize 

Иж ------------------------------------------------------------------------- */ 
expose u 


use arg dummy,sizeinfo 
/* wait for last size event msg then resize */ 
if self^PeekDialogMessage^left(8) \= "OnResize" then u^resize(self,sizeinfo) 


This achieves the same dialog as the previous DlgArea example, but now it is resizable by dragging the 
frame. 
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10.8. VirtualKeyCodes Class 


The methods of the VirtualKeyCodes class can be used for all objects of the WindowsProgramManager 
and WindowObject classes. These classes inherit from the VirtualKeyCodes class. The VirtualKeyCodes 
class cannot be used as a standalone class. 


The VirtualKeyCodes class requires the class definition file WinSystm. cls: 


::requires "WinSystm.cls" 


10.8.1. Methods of the VirtualKeyCodes Class 


Instances of the VirtualKeyCodes class implement the methods described in the following sections. 


10.8.1.1. VCode 


»»-aVirtualKeyCodes^VCode (--keyname--)------------------------- >< 


The VCode method returns the decimal value of a symbolic key name. 


Arguments: 


The only argument is: 


keyname 


The symbolic key name. See Symbolic Names for Virtual Keys for a list of key names. 


Return value: 


The decimal value of the symbolic key name. If the symbolic name is not found, 255 is returned. 


10.8.1.2. KeyName 


>>-aVirtualKeyCodes~KeyName (--vcode--)------------------------- >< 


The KeyName method returns the symbolic key name of the specified hexadecimal code. 


Arguments: 


The only argument is: 


vcode 


The hexadecimal code of the key. 


Return value: 


The symbolic key name of the specified code. 
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Example: 


The following example deletes or inserts an item in a tree view depending on the selected key: 


::method OnKeyDown_IDC_TREE 
use arg treeld, key 


curTree - self^GetTreeControl(treeId) 


/* if the Delete key is pressed, delete the selected item */ 


if self^KeyName(key) = "DELETE" then 
curTree^Delete(curTree^Selected) 


else 


/* if the Insert key is pressed, simulate pressing the New button */ 


if self^KeyName(key) - "INSERT" then 


Self^IDC PB. NEW 


10.8.2. Symbolic Names for Virtual Keys 


Symbolic Names for Virtual Keys shows the symbolic names and the keyboard equivalents for the virtual 


keys used by Object Rexx: 


Table 10-8. Symbolic Names for Virtual Keys 





Symbolic Name 


Mouse or Keyboard Equivalent 







































































LBUTTON Left mouse button 
RBUTTON Right mouse button 
CANCEL Control-break processing 
MBUTTON Middle mouse button (three-button mouse) 
BACK BACKSPACE key 
TAB TAB key 

CLEAR CLEAR key 
RETURN ENTER key 

SHIFT SHIFT key 
CONTROL CRTL key 

MENU ALT key 

PAUSE PAUSE key 
CAPITAL CAPS LOCK key 
ESCAPE ESC key 

SPACE SPACEBAR 
PRIOR PAGE UP key 
NEXT PAGE DOWN key 
END END key 

HOME HOME key 

LEFT LEFT ARROW key 
UP UP ARROW key 
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Symbolic Name 


Mouse or Keyboard Equivalent 





RIGHT 


RIGHT ARROW key 





DOWN 


DOWN ARROW key 





SELECT 


SELECT key 





EXECUTE 


EXECUTE key 





SNAPSHOT 


PRINT SCREEN key 





INSERT 


INS key 





DELETE 


DEL key 





HELP 


HELP key 





0 key 





1 key 





2 key 





3 key 





4 key 





5 key 





6 key 





7 key 





8 key 





9 key 





A key 





B key 





C key 





D key 





E key 





F key 





G key 





H key 





І key 





J key 





K key 





L key 





M key 





N key 





O key 





О key 





R key 





S key 





T key 
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U key 
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Symbolic Name 


Mouse or Keyboard Equivalent 





























































































































V V key 

W W key 

X X key 

Y Y key 

7. Z key 

NUMPADO Numeric keypad 0 key 
NUMPADI Numeric keypad 1 key 
NUMPAD2 Numeric keypad 2 key 
NUMPAD3 Numeric keypad 3 key 
NUMPAD4 Numeric keypad 4 key 
NUMPAD5 Numeric keypad 5 key 
NUMPAD6 Numeric keypad 6 key 
NUMPAD7 Numeric keypad 7 key 
NUMPAD8 Numeric keypad 8 key 
NUMPAD9 Numeric keypad 9 key 
MULTIPLY Multiply key 

ADD Add key 
SEPARATOR Separator key 
SUBTRACT Subtract key 
DECIMAL Decimal key 

DIVIDE Divide key 

Fl F1 key 

F2 F2 key 

F3 F3 key 

F4 F4 key 

F5 F5 key 

F6 F6 key 

F7 F7 key 

F8 F8 key 

F9 F9 key 

F10 F10 key 

Е11 F11 key 

F12 F12 key 

F13 F13 key 

Е14 Е14 Кеу 

Е15 Е15 Кеу 

Е16 F16 key 

F17 F17 key 
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Symbolic Name Mouse or Keyboard Equivalent 
F18 F18 key 

F19 F19 key 

F20 F20 key 

F21 F21 key 

F22 F22 key 

F23 F23 key 

F24 F24 key 

NUMLOCK NUM LOCK key 

SCROLL SCROLL LOCK key 
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To use the methods defined by the mixin class MessageExtensions you must inherit from this class by 
specifying the INHERIT option for the ::CLASS directive in the class declaration. For example: 


::class MyExtendedDialog SUBCLASS UserDialog INHERIT MessageExtensions 


Requires: 
The MessageExtensions class requires the class definition file oodwin32.cls: 
::requires oodwin32.cls 

Methods: 


Instances of the MessageExtensions class implement the methods listed in MessageExtensions 
Instance Methods table. 


Table 11-1. MessageExtensions Instance Methods 





















































Method... ..оп page 
connectButtonNotify connectButtonNotify 
ConnectComboBoxNotify ConnectComboBoxNotify 
ConnectCommonNotify ConnectCommonNotify 
ConnectEditNotify ConnectEditNotify 
ConnectListBoxify ConnectListBoxNotify 
ConnectListNotify ConnectListNotify 
ConnectList ViewNotify ConnectList ViewNotify 
ConnectScrollBarNotify ConnectScrollBarNotify 
ConnectSliderNotify ConnectScrollBarNotify 
ConnectStaticNotify connectStaticNotify 
ConnectTabNotify ConnectTabNotify 
ConnectTreeNotify ConnectTreeNotify 
DefListDragHandler DefListDragHandler 
DefTreeDragHandler DefTreeDragHandler 








11.1. ConnectCommonNotify 


>>-aMessageExtensions~ ConnectCommonNotify (--14--,--"--+-00ТОЕМЕМОВУ- +--> 
T-CLIOK------- * 
*T-DBECEK----—-- * 
*-ENTER------- + 
+=RCLICK====== + 
*-RDBLCLK----- * 


*-GOTFOCUS-----4 
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+-LOSTFOCUS---+ 


>--"--+--------------- +--)------------------------------------- >< 


+-,--msgToRaise-+ 


The ConnectCommonNotify method connects a particular WM_NOTIFY message for a dialog control 
with a method. The WM_NOTIFY message informs the dialog that an event has occurred with regard to 
a dialog control. 


If a specific Connect...Notify method exists for the dialog control, use this method instead of the 
ConnectCommonNotify method because the system might send a specific notification instead of a 
common one. 


Arguments: 


The arguments are: 


id 
The ID of the dialog control of which a notification is to be connected to a method. 


event 


The event to be connected with a method: 


OUTOFMEMORY 


The dialog control went out of memory. 


CLICK 


The left mouse button was clicked on the dialog control. 


DBLCLK 


The left mouse button was double-clicked on the dialog control. 


ENTER 


The return key was pressed in the dialog item. 


RCLICK 


The right mouse button was clicked on the dialog item. 


RDBLCLK 


The right mouse button was double-clicked on the dialog control. 


GOTFOCUS 


The dialog item got the input focus. 


LOSTFOCUS 


The dialog item lost the input focus. 
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msgToRaise 


The message that is to be sent whenever the specified notification is received. Provide a 
method with a matching name. If you omit this argument, the event is preceded by On. 


Return value: 


The return codes are: 


0 
No error detected. 
-1 
The resource ID could not be resolved or the event argument is incorrect. 
1 
The message was not connected correctly. 
Example: 


The following example connects the double-click of the left mouse button on dialog control 
DLGITEMI with method OnDbIClk: 


::class MyDlgClass subclass UserDialog inherit MessageExtensions 


::method Init 
self~init:super(...) 
self~ConnectCommonNotify(DLGITEM1, "DBLCLK") 


::method OnDblClk 
use arg id 
say "Item" id " has been double-clicked!" 


Note: Connections are usually placed in the Init or InitDialog method. If both methods are defined, 
use init as the place for this connection - but not before init:super has been called. 


11.2. ConnectTreeNotify 


»»-aMessageExtensions^ConnectTreeNotify (--id--,--"--*-BEGINDRAG---4--"--» 
+-BEGINRDRAG--+ 
+-BEGINEDIT---+ 
*-ENDEDIT----- * 
+-DEFAULTEDIT-+ 
+-EXPANDING---+ 
+-ЕХРАМрЕр----+ 
+-РрЕГЕТЕ------ + 
*-KEYDOWN----- * 
+-SELCHANGING-+ 
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+-SELCHANGED--+ 


>--+--------------- oo) SoS ass Sess >< 


*-,--msgToRaise-* 


The ConnectTreeNotify method connects a particular WM NOTIFY message for a tree view control 
with a method. The WM. NOTIFY message informs the dialog that an event has occurred in the tree 


view. 


Arguments: 


The arguments are: 


id 
The ID of the tree view control of which a notification is to be connected to a method. 


event 


The event to be connected with a method: 


BEGINDRAG 
A drag-and-drop operaton was initiated. See DefTreeDragHandler for information on how 
to implement a drag-and-drop handler. 
BEGINRDRAG 
A drag-and-drop operaton involving the right mouse button was initiated. See 
DefTreeDragHandler for information on how to implement a drag-and-drop handler. 
BEGINEDIT 
Editing a label has been started. 


ENDEDIT 
Label editing has ended. 


DEFAULTEDIT 


This event connects the notification that label editing has been started and ended with a 
predefined event-handling method. This method extracts the newly entered text from the 
notification and modifies the item of which the label was edited. If this event is not 
connected you must provide your own event-handling method and connect it with the 
BEGINEDIT and ENDEDIT events. Otherwise, the edited text is lost and the item 
remains unchanged. 


When you specify this event, omit the msgToRaise argument. 


EXPANDING 


An item is about to expand or collapse. This notification is sent before the item has 
expanded or collapsed. 
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EXPANDED 


An item has expanded or collapsed. This notification is sent after the item expanded or 
collapsed. 


DELETE 


An item has been deleted. 


KEYDOWN 


A key was pressed inside the tree view. This notification is not sent while a label is being 
edited. 


SELCHANGING 


Another item is about to be selected. This notification is sent before the selection has 
changed. 


SELCHANGED 


Another item was selected. This notification is sent after the selection was changed. 


msgToRaise 


The message that is to be sent whenever the specified notification is received from the tree 
view control. Provide a method with a matching name. If you omit this argument, the event is 
preceded by On. 


Return value: 


The return codes are: 


Example: 


No error detected. 


The resource ID could not be resolved or the event argument is incorrect. 


The message was not connected correctly. 


The following example connects the selection-changed event for the tree view FileTree with method 
NewTreeSelection and displays the text of the new selection: 


::class MyDlgClass subclass UserDialog inherit MessageExtensions 


::method Init 
self~init:super(...) 
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self~ConnectTreeNotify("FileTree", "SELCHANGED", "NewTreeSelection") 


::method NewTreeSelection 
tc = self^GetTreeControl("FileTree") 
info. = tc^ItemInfo(tc^Selected) 
say "New selection is:" info.!text 


Note: 


1. Connections are usually placed in the Init or InitDialog method. If both methods are defined, use 
init as the place for this connection - but not before init:super has been called. 


2. The event-handling method connected to ENDEDIT receives two arguments: the item handle of 
which the label has been edited and the newly entered text. Example: 


::method OnEndEdit 
use arg item, newText 


3. The event-handling method connected to KEYDOWN receives two arguments: the control ID of 
the tree view control and the virtual key code pressed. Use the method KeyName of the 
VirtualKeyCodes class to get the name of the key. Note that your class must inherit from the 
VirtualKeyCodes class to use the KeyName method. Example: 

::method OnKeyDown 
use arg id, vkey 
say "Key" self^KeyName(vkey) "was pressed." 

4. The event-handling method connected to EXPANDED or EXPANDING receives three 
arguments: the control ID of the tree view control, the tree item expanded or collapsed, and a 
string that indicates whether the item was expanded or collapsed. Example: 


::method OnExpanding 

use arg id, item, what 

say "Item with handle" item "is going to be" what 

5. The event-handling method connected to BEGINDRAG or BEGINRDRAG receives three 

arguments: the control ID of the tree view control, the tree item to be dragged, and the point 
where the mouse cursor was pressed (x and y positions, separated by a blank). Example: 
::method OnBeginDrag 

use arg id, item, where 

say "Item with handle" item "is in drag-and-drop mode" 

parse var where x y 

say "The drag operation started at point ("x","y")" 


11.3. DefTreeDragHandler 


»»-aMessageExtensions^DefTreeDragHandler----------------------- >< 


A tree view control cannot handle a drag-and-drop operation within the tree view. Therefore, you can 
connect the DefTreeDragHandler method with the BEGINDRAG or BEGINRDRAG notification 
message (see ConnectTreeNotify) to allow the moving of an item or a node with all its subitems from 
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one parent node to another within a tree view. The cursor shape is changed to a crosshair during the drag 
operation. If the cursor is moved over the item dragged, the cursor shape is changed to a slashed circle. 
You can cancel the drag operation by clicking the other mouse button while holding the button that 
started the drag operation. 


The DefTreeDragHandler is implemented as follows: 


::method DefTreeDragHandler 
use arg id, item, pt 
tc = self~GetTreeControl (id) 
hc = tc^Cursor. Cross /* change cursor and store current */ 
parse value tc^GetRect with left top right bottom 
oldItem = 0 
посигв = 0 
lmb = self~IsMouseButtonDown ("LEFT") 
rmb = self~IsMouseButtonDown ("RIGHT") 
call time "R" 
do while (lmb \= О | rmb \= 0) & N(1mb \= 0 & rmb \= 0) 
pos = self^CursorPos 
parse var pos x y 
parse value tc^ScreenToClient(x, y) with newx newy 
ht = tc^HitTest(newx, newy) 
if ht \= 0 & ht^wordpos("ONITEM") > O then do 
parse var ht newParent where 
/* check if droptarget is the current parent or one of the dragged 
item&apos;s children */ 
if newParent \= Item & newParent \= tc^Parent(Item) & tc^IsAncestor, 
(Item,newParent) = 0 


then do 
is. = tc^ItemInfo(newParent) 
if is.!State^Wordpos("INDROP") = 0 then 
do 


call time "R" 
tc^DropHighlight (newParent ) 
if nocurs \= 0 then do 
tc^RestoreCursorShape(nocurs) /*restore old cursor (cross)*/ 
nocurs = 0 
end 
end 
else if time("E") > 1 then do /* expand node after 1 second */ 
if is.!Children \= 0 & is.!State^Wordpos("EXPANDED") = 0 then 
tc~ expand (newParent) 
end 
end 
else do 


if nocurs = 0 then do 
nocurs = tc^Cursor No /* set no cursor and retrieve 
current cursor (cross) */ 
tc^DropHighlight /* remove drop highlight */ 
end 
end 
end 
else do 
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if newParent \= 0 then do 
/* necessary to redraw cursor when moving on a valid item again */ 
tc^DropHighlight /* remove drop highlight */ 
newParent = 0 
end 
if nocurs = 0 then nocurs = tc^Cursor No /* set no cursor and 
retrieve current cursor (cross) */ 
/* handle scrolling */ 
fvItem = tc^FirstVisible 
if (ybottom) & (tc~NextVisible(fvItem) АЕ 0) then do 
tc^MakeFirstVisible(tc^NextVisible(fvItem)) 
if y-bottom < 200 then call msSleep 200-(y-bottom) 


end 
end 
lmb = self^IsMouseButtonDown("LEFT") 
rmb = self~IsMouseButtonDown ("RIGHT") 
end 


if ht^wordpos("ONITEM") > O & 1mb = O & rmb = 0 then do /* if mouse on item 
and both mouse buttons up */ 
item = tc^Moveltem(Item, newParent, 1) /* move item under newParent */ 


end 
tc^DropHighlight(0) /* remove drop highlight */ 
tc~select (item) /* select item */ 


tc^EnsureVisible(item) 

tc^RestoreCursorShape(hc) /* restore old cursor */ 

pos = self^CursorPos 

parse var pos x y 

self^SetCursorPos(x*i, y*1) /ж move cursor to force redraw */ 


11.4. ConnectListNotify 


»»-aMessageExtensions^ConnectListNotify(--id--,--"--*-ACTIVATE----4--"--» 
*-BEGINDRAG----* 
+-BEGINRDRAG--+ 
+-ВЕСТНЕРТТ---+ 
*-ENDEDIT----- * 
+-DEFAULTEDIT-+ 
+-СНАМСІМС----+ 


*-CHANGED----- + 
+-COLUMNCLICK-+ 
*-DELETE------ * 


+-DELETEALL---+ 
+-INSERTED----+ 
+-KEYDOWN----- + 


>--+--------------- 4--)---------------------------------------- >< 
+-,--msgToRaise-+ 


448 ooRexx OODialog Reference Version 4.0.0 


Chapter 11. MessageExtensions Class 


The ConnectListNotify method connects a particular WM_NOTIFY message for a list view control with 
a method. Тһе WM, NOTIFY message informs the dialog that an event has occurred in the list view. 


Arguments: 


The arguments are: 


id 
The ID of the list view control of which a notification is to be connected to a method. 


event 


The event to be connected with a method: 


ACTIVATE 


An item is activated by double-clicking the left mouse button. 


BEGINDRAG 
A drag-and-drop operaton was initiated. See DefListDragHandler for information on how 
to implement a drag-and-drop handler. 
BEGINRDRAG 
A drag-and-drop operaton involving the right mouse button was initiated. See 
DefListDragHandler for information on how to implement a drag-and-drop handler. 
BEGINEDIT 


Editing a label has been started. 


ENDEDIT 
Label editing has ended. 


DEFAULTEDIT 


This event connects the notification that label editing has been started and ended with a 
predefined event-handling method. This method extracts the newly entered text from the 
notification and modifies the item of which the label was edited. If this event is not 
connected you must provide your own event-handling method and connect it with the 
BEGINEDIT and ENDEDIT events. Otherwise, the edited text 1s lost and the item 
remains unchanged. 


When you specify this event, omit the msgToRaise argument. 


CHANGING 


An item is about to change. This notification is sent before the item is changed. 


CHANGED 


An item has changed. This notification is sent after the item changed. 
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COLUMNCLICK 


A column has been clicked. 


DELETE 


An item has been deleted. 


DELETEALL 


All items have been deleted. 


INSERTED 


A new item has been inserted. 


KEYDOWN 


A key was pressed inside the list view. This notification is not sent while a label is being 
edited. 


msgToRaise 


The message that is to be sent whenever the specified notification is received from the list view 
control. Provide a method with a matching name. If you omit this argument, the event is 
preceded by On. 


Return value: 


The return codes are: 


0 
No error detected. 
-1 
The resource ID could not be resolved or the event argument is incorrect. 
1 
The message was not connected correctly. 
Example: 


The following example connects the column-clicked event for the list view EMPLOYEES with 
method ColumnAction and changes the style of the list view from REPORT to SMALLICON: 


::class MyDlgClass subclass UserDialog inherit MessageExtensions 
::imethod Init 


self~init:super(...) 
self~ConnectListNotify("EMPLOYEES", "COLUMNCLICK", "ColumnAction") 


::method ColumnAction 


use arg id, column 
lc = self^GetListControl("EMPLOYEES") 
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lc^ReplaceStyle("REPORT", "SMALLICON EDIT SINGLESEL ASCENDING") 
if column > O then ... 


1. Connections are usually placed in the Init or InitDialog method. If both methods are defined, use 
init as the place for this connection - but not before init:super has been called. 


2. The event-handling method connected to ENDEDIT receives two arguments: the item ID of 
which the label has been edited and the newly entered text. 


Example: 


::method OnEndEdit 
use arg item, newText 
3. The event-handling method connected to COLUMNCLICK receives two arguments: the control 
ID of the list view control and the zero-based column number of which the header button was 
pressed. 


Example: 


::method OnColumnClick 
use arg id, column 
4. The event-handling method connected to KEYDOWN receives two arguments: the control ID of 
the list view control and the virtual key code pressed. Use the method KeyName of the 
VirtualKeyCodes class to get the name of the key. Note that your class must inherit from the 
VirtualKeyCodes class to use the KeyName method. 


Example: 


::method OnKeyDown 
use arg id, vkey 
say "Key" self^KeyName(vkey) "was pressed." 

5. The event-handling method connected to BEGINDRAG or BEGINRDRAG receives three 
arguments: the control ID of the list view control, the index of the list item to be dragged, and the 
point where the mouse cursor was pressed (x and y positions, separated by a blank). 

Example: 


::method OnBeginDrag 
use arg id, item, where 
say "Item at index" item "is in drag-and-drop mode" 
parse var where x y 
say "The drag operation started at point ("x","y")" 


11.5. DefListDragHandler 


»»-aMessageExtensions^DefListDragHandler----------------------- >< 


A list view control cannot handle a drag-and-drop operation within the list view. Therefore, you can 
connect the DefListDragHandler method with the BEGINDRAG or BEGINRDRAG notification 
message (see ConnectListNotify) to allow the dragging of an item from one location to another within an 
icon view and a smallicon view. The cursor shape is changed to a crosshair during the drag operation. 
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You can cancel the drag operation by clicking the other mouse button while holding the button that 
started the drag operation. Note that the item position is not flexible when the list view control has the 
AUTOARRANGE style. 


The DefListDragHandler is implemented as follows: 


::method DefListDragHandler 
use arg id, item, pt 
1с = self~GetListControl (id) 
hc = 1c^Cursor. Cross /* change cursor and store current */ 
parse value lc^GetRect with left top right bottom 
parse var pt oldx oldy 
origin = lc^ItemPos(item) 
lmb = self^IsMouseButtonDown("LEFT") 
rmb = self^IsMouseButtonDown ("RIGHT") 
do while (lmb \= 0 | rmb \= 0) & N(1mb \= О & rmb \= 0) 
pos = self^CursorPos 
parse var pos x y 
parse value lc^ScreenToClient(x, y) with newx newy 
hs = l1c^HScrollPos; vs = lc^VScrollPos 
Sx 


x-right 

Sy = y-bottom 

in rx = (sx <= 30) & (newx >= -30) 

in ry = (sy <= 30) & (newy >= -30) 

if (in rx & in ry) then do /* is the mouse cursor inside the drag 

rectangle */ 

if xright then sx - sx * 30; else sx - O 
if ybottom then sy = sy + 30; else sy = O 
newx = newxths; newy = newy +ув; 

0 

if newy < 0 then newy = 0 


if newx < 0 then newx 


if (in_rx & oldx \= newx) | (in_ry & oldy \= newy) then do 
lc^SetItemPos(item, newx, newy) 
oldx = newx 
oldy = newy 
if sx \= 0 | sy \= 0 then do 
lc^Scroll(sx, sy) 
call msSleep 30 


end 
end 
end 
else do /* no, so force the mouse cursor back inside the rectangle */ 
if newx < -30 then newx = -30 


if sx > 30 then newx = (right-left) + 28 

if newy < -30 then newy = -30 

if sy > 30 then newy = (bottom-top) + 28 

parse value lc^ClientToSCreen(newx, newy) with x у 
self~SetCursorPos(x, y) 


end 

1ш] = self~IsMouseButtonDown ("LEFT") 

rmb = self~IsMouseButtonDown ("RIGHT") 
end 


if (1mb \= 0 & rmb \= 0) then do /* if both buttons pressed restore 
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original pos */ 

parse var origin x y 

lc^SetItemPos(item, x, y) 
end 
lc^RestoreCursorShape(hc) /* restore old cursor */ 
pos = self^CursorPos 
parse var pos x y 
self^SetCursorPos(x*i, y*1) /* move cursor to force redraw */ 


11.6. ConnectListViewNotify 


»»-aMessageExtensions^ConnectListViewNotify (--id--,--------------------- ? 
»--"--4-CLICK-------------- dont peececlcenee—- *--)------------2---- >< 
*-CHECKBOXCHANGED-- --- +-,--methodName-+ 
+-SELECTCHANGED------ + 
*-FOCUSCHANGED-- ----- * 


+-SELECTFOCUSCHANGED-+ 


Microsoft continually enhances the Windows User Interface and therefore the dialog controls evolve over 
time. The ConnectListViewNotify method is similar to the ConnectListNotify method, but it is designed 
to take advantage of new features in the list-view control. It connects notification message sent by a list 
view control to its parent dialog with a method, provided by the programmer, in an ooDialog class. These 
notifications inform the dialog that an event has occurred in the list view. 


The ConnectListViewNotify method is designed to provide more information to the invoked method 
than the ConnectListNotify or ConnectCommonNotify methods. Connecting an event through the 
ConnectListViewNotify method is used as а replacement for connecting the same event through the 
ConnectListNotify method or the ConnectCommonNotify method. 


Note: If the same event, for the same control, is connected using two different ConnectXXX 
methods, only one connection will be in effect. This will be the connection whose ConnectXXX 
method is invoked first. For example, take a dialog that has a list view control with resource ID of 
109. If the mouse click event is connected for that control using the ConnectCommonNotify method and 
then the mouse click event is also connected using the ConnectListViewNotify method, only one 
connection will be active. Which one is active is dependent on the order of invocation of the 
ConnectXXX methods. 


Each of the events that can be connected through the ConnectListViewNotify method is a replacement 
for connecting that event through one of the other ConnectXXX methods. The argument documentation 
provides more detail on this. 
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Arguments: 


The arguments are: 


id 

The ID of the list view control for which the event is to be connected to a method. 

event 

The event to be connected with a method: 

Note: When using ConnectListViewNotify a separate method can be connected to each of the 
checkbox changed, selection changed, and focus changed events. These event 
connectionss are all replacements for the ConnectListNotify method’s CHANGED event. 

CLICK 
An item was clicked with the left mouse button. Connecting the CLICK event is a 
replacement for the ConnectCommonNotify method’s CLICK event. 

CHECKBOXCHANGED 
The check box state of an item changed. (The check box was checked or unchecked.) This 
event can only occur if the list view has the check box extended list view style. 

SELECTCHANGED 
The selection state of an item changed. (The item was selected or unselected.) 

FOCUSCHANGED 
The focus state of an item changed. (The item gained or lost the focus.) 

SELECTFOCUSCHANGED 
The selection state or the focus state of an item changed. This event argument combines 
the selection changed and the focus changed event into one connection. When this event 
is connected, separate selection changed and focus changed events can not be connected. 
This keyword can be abbreviated to "SELECTFOCUS". 

methodName 


The method that is to be invoked whenever the specified event occurs. Provide a method with a 
matching name in the dialog class. If you omit this argument, a default method name will be 
constructed. This name will be the name of the event preceded by On. 
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Return value: 


The return codes are: 


0 
No error detected. 
-1 
The resource ID could not be resolved ог Ше event argument is incorrect. 
1 
The event was not connected correctly to a method. 
Event Methods 


The following details the method signature for each of the ConnectListViewNotify events: 


CLICK 


The method invoked for the left mouse click event recieves four arguments. 


::method onClick 
use arg id, itemIndex, columnIndex, keyState 


id 
The resource ID of the list view control whose item was clicked. 


itemIndex 


The index of the item that was clicked. 


columnIndex 


The index of the subitem that was clicked. This will be the column clicked on if the list 
view is in report view. In other views it will be 0. 


keyState 


This argument reports the state of the shift, control, and alt keys at the time of the mouse 
click. The argument is a string of keywords separated by blanks. The keywords consist of: 
SHIFT, CONTROL, ALT, or NONE. The presence of a keyword indicates the key was 
held down when the user clicked on the list view control. NONE of course indicates that 
none of the keys were down. If the user managed to hold all three of the keys down at the 
time of the mouse click, the argument would be the string: "SHIFT CONTROL ALT" 


CHECKBOXCHANGED 


The method invoked for the checkbox changed event recieves three arguments. The method 
signature will look as follows: 


::method onCheckboxChanged 
use arg id, itemIndex, state 
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id 
The resource ID of the list view control whose item had the checkbox state changed. 


itemIndex 


The index of the item whose checkbox was changed. 


state 


This argument reports whether the check box was checked or unchecked. Its value will be 
either "CHECKED" or "UNCHECKED" 


SELECTCHANGE 


The method invoked when the selection changes will recieve three arguments. The method 
signature will look as follows: 


::method onSelectChanged 
use arg id, itemIndex, state 


id 
The resource ID of the list view control whose item had the selection changed. 


itemIndex 


The index of the item whose selection was changed. 


state 


This argument reports whether the item was selected or unselected. Its value will be either 
"SELECTED" or "UNSELECTED" 


FOCUSCHANGED 


The method invoked for the focus changed event recieves three arguments. The method 
signature will look as follows: 


::method onFocusChanged 
use arg id, itemIndex, state 


id 
The resource ID of the list view control whose item had the focus changed. 


itemIndex 


The index of the item which gained or lost the focus. 


state 


This argument reports whether the focus was gained or lost. Its value will be either 
"FOCUSED" or "UNFOCUSED" 
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SELECTFOCUSCHANGED 
The method invoked for the selection or focus changed event recieves three arguments. The 


method signature will look as follows: 


::method onSelectFocusChanged 
use arg id, itemIndex, state 


id 
The resource ID of the list view control whose item had the either the focus or the 
selection changed. 


itemIndex 


The index of the item where the state was changed. 


state 


This argument reports whether the focus was gained or lost and whether the selection was 
gained or lost. Its value will contain at least one of the keywords: "SELECTED", 
"UNSELECTED", "FOCUSED" or "UNFOCUSED". It is possible for both the selection 
and focus changed to be reported at once, however sometimes each change is reported 
separately. (This has nothing to do with ooDialog, itis how the operating system sends 
the messages.) 


Example: 


The following example is from an address book application. A list view control is filled with the 
information from the address book, one item for each entry. The check box changed event is 
connected to the onCheckboxChanged method. The onCheckboxChanged method will receive 3 
arguments: the resource ID of the control, the index of the item whose check box changed, and the 
changed state. If the user checks the check box, that entry is added to a mail merge being 
constructed. If the user unchecks the box, the entry is removed from the mail merge. 


::class MailingListDlg subclass UserDialog inherit AdvancedControls MessageExtensions 
::method initDialog 
expose mailList 


mailList = self^getListControl(IDC, LV. ADDRESSES) 


-- Since the methodName argument is omitted, ooDialog will construct a default 
-- name of ’onCheckboxChanged’ 
self^connectListViewNotify (IDC LV. ADDRESSES, "CHECKBOXCHANGED") 


: :method onCheckboxChanged 
expose mailList 


use arg id, itemIndex, state 


if state -- "CHECKED" then 
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self~addToMailMerge(mailList, itemIndex) 
else 
self~removeFromMailMerge(mailList, itemIndex) 


11.7. connectButtonNotify 


>>--connectButtonNotify (--id--,--"--event---'"--4--------------- +--)--------- >< 
+-,--msgToRaise-+ 


The connectButtonNotify method connects a particular WM_NOTIFY message for a button control 
(push button, radio button, or check box) with a method. The WM_NOTIFY message informs the dialog 
that an event has occurred with regard to the button. 


Note: In order to recieve the GOTFOCUS, LOSTFOCUS, and DBLCLK events, the button control 
has to have the NOTIFY (BS_NOTIFY) style. For user defined dialogs use the NOTIFY style keyword 
in the Add... method when the button is defined. For dialogs created from a compiled resource or a 
resource script file use the BS_NOTIFY style for the button resource. The other events are always 
sent and it is not necessary to add the NOTIFY style. 


Arguments: 


The arguments are: 


id 
The ID of the button control of which a notification is to be connected to a method. 


event 


A keyword specifying the event to be connected with a method. This can be exactly one of the 
follwoing: 


CLICKED 
The button has been clicked. 


DBLCLK 


The button has been double-clicked. 


DISABLE 
The button has been disabled. 


GOTFOCUS 


The button got the input focus. 


LOSTFOCUS 


The button lost the input focus. 
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HILITE 


The button has been selected. 


UNHILITE 


The highlighting is to be removed (lost selection). 


HOTITEM 


Notifies the dialog that the mouse has moved over the button, or that the mouse is leaving 
the area over the button. 


PAINT 


The button is to be repainted. This notification is only sent for owner-drawn buttons. 


msgToRaise 


The message that is to be sent whenever the specified notification is received from the button 
control. Provide a method with a matching name. If you omit this argument, a message name is 
generated automatically. The name consists of the event keyword preceded by On. For instance: 


onGotFocus. 


Return value: 


The return codes are: 


0 
No error detected. 
-1 
The resource ID could not be resolved or the event argument is incorrect. 
1 
The message was not connected correctly. 
Additional Notes: 


1. The invocation of connectButtonNotify() can be placed in the init or initDialog method. 
(Indeed the invocation can be done anywhere. But, it makes most sense to have the connection 
made before the dialog starts executing.) If the connection is made in the init() method, be sure 
that the super class init() is invoked first. 


2. For all events other than the HOTITEM event, the event-handling methods will receive two 
arguments. The first arg contains information about the specific control and its event. The 
second arg is the window handle of the button control. 


The low word of the first arg is the control ID and the high word is the event ID. Example: 


::method handler 
use arg info, handle 
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id = .DlgUtil~loWord (info) 


3. The method for the HOTITEM event also receives two arguments. The first arg is the control 
id. The second arg is .true or .false. True if the mouse moved over the button, false if it left the 
area over the button. Example: 


::method onHover 


use arg id, entering 


say ’onHover id:' id "entering: entering 


/* Output 
onHover 
onHover 


onHover 
onHover 


*/ 


Example: 


might be: 
id: 1044 
id: 1044 
id: 1001 
id: 1001 


entering: 
entering: 
entering: 
entering: 


он о Hn 


The following example displays a message whenever the OK button is selected: 


::class MyDlgClass subclass UserDialog inherit MessageExtensions 


::method Init 


self~init:super(...) 
self^connectButtonNotify("OK", "HILITE") 


::method OnHilite 


say "The ОК button has been selected" 


11.8. connectStaticNotify 


»»--connectStaticNotify (--id--,--"event"--,-4--------------- +--)-------- >< 


+-,--methodName-+ 


The connectStaticNotify connects a notification message from a static control to a method, defined by 
the programmer, of the dialog. Normally, static controls do not send notification messages. A static 
control will only send the messages when it has the SS_NOTIFY style. The notification messages inform 
the dialog that an event has occurred with regard to the static control. 


For user defined dialogs use the NOTIFY style keyword in the Add... static control methods when the 
control is defined. For dialogs created from a compiled resource or a resource script file use the 
55 NOTIFY style when defining the control in a resource editor. 
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Arguments: 


The arguments are: 


id 
The resource ID of the static control. 
event 


A keyword specifying the event to be connected with a method: 


CLICK 

The static control has been clicked with the mouse. 
DBLCLK 

The static control has been double-clicked with the mouse. 
DISABLE 

The static control has been disabled. 


ENABLE 


The static control has been enabled. 


methodName 


The method that is to be invoked whenever the specified notification is received from the static 
control. The programmer defines this method. If this argument is omitted, a method name is 
automatically generated that consists of the event keyword preceded by on. For instance, 
onClick. 


Return value: 


The return codes are: 


0 
No error detected. 
-1 
The resource ID could not be resolved or the event argument is incorrect. 
1 
The message was not connected correctly. 
Additional Notes: 


1. The invocation of connectStaticNotify() can be placed in the init or initDialog method. (Indeed 
the invocation can be done anywhere. But, it makes most sense to have the connection made 
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before the dialog starts executing.) If the connection is made in the init() method, be sure that 
the super class init() is invoked first. 


2. The defined event-handling methods will receive two arguments. The first arg contains 
information about the specific control and its event. The second arg is the window handle of the 
static control. 


The low word of the first arg is the control ID and the high word is the event ID. 


Example: 


The following example comes from an application that displays employee statistics. A single click 
on the employee number field advances the display to the next employee. A double click on either 
the employee name or employee job duties alllows those fields to be edited. 


::method initDialog 
self~connectStaticNotify(IDC_ST_EMPNO, "CLICK", empLookup) 


self~connectStaticNotify(IDC_ST_EMPJOB, "DBLCLK", editStats) 
self^connectStaticNotify (10С ST EMPNAME, "DBLCLK", editStats) 


first - self^initDatabase 
self^setStats(first) 





In this example, (a continuation of the above example.) the control ID determines if the user has 
double clicked on the employee job duties field, or the employee name field. The event ID is not 
used, or needed. Its purpose in the code snippet is simply an example. The same thing applies to the 
window handle. 


::method editStats 
use arg ctrlInfo, ctrlHwnd 


ctrlID = .DlgUtil^loWord(ctrlInfo) 
eventID = .DlgUtil^hiWord(ctrlInfo) 


rec = self^getCurrentRecord 


if self^userUpdate(ctrlID, rec) then self^setStats(rec) 


11.9. ConnectEditNotify 


»»-aMessageExtensions^ConnectEditNotify (--id--,--"--*-CHANGE----4--"--» 
+-UPDATE----+ 
+-ERRSPACE--+ 
+-МАХТЕХТ---+ 
+-HSCROLL---+ 
+-VSCROLL---+ 
+-GOTFOCUS--+ 
+-LOSTFOCUS-+ 
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>--+--------------- 4--)---------------------------------------------- >< 


*-,--msgToRaise-* 


The ConnectEditNotify method connects a particular WM. NOTIFY message for an edit control with a 
method. The WM NOTIFY message informs the dialog that an event has occurred with regard to the 
edit control. 


Arguments: 


The arguments are: 
id 
The ID of the edit control of which a notification is to be connected to a method. 


event 


The event to be connected with a method: 


CHANGE 


The text has been altered. This notification is sent after the screen has been updated. 


UPDATE 


The text has been altered. This notification is sent before the screen is updated. 


ERRSPACE 


An out-of-memory problem has occurred. 


MAXTEXT 


The text inserted exceeds the specified number of characters for the edit control. This 
notification is also sent when: 


* An edit control does not have the ES AUTOHSCROLL ог AUTOSCROLLH style and 
the number of characters to be inserted would exceed the width of the edit control. 


* The ES AUTOVSCROLL or AUTOSCROLLV style is not set and the total number of 
lines resulting from a text insertion would exceed the height of the edit control. 


HSCROLL 


The horizontal scroll bar has been used. 


VSCROLL 


The vertical scroll bar has been used. 


GOTFOCUS 


The edit control got the input focus. 
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LOSTFOCUS 


The edit control lost the input focus. 


msgToRaise 


The message that is to be sent whenever the specified notification is received from the edit 
control. Provide a method with a matching name. If you omit this argument, the event is 
preceded by On. 


Return value: 


The return codes are: 


0 
No error detected. 
-1 
The resource ID could not be resolved or the event argument is incorrect. 
1 
The message was not connected correctly. 
Example: 


The following example verifies the input of entry line AMOUNT and resets it to 0 when а 
nonnumeric value was entered: 


::class MyDlgClass subclass UserDialog inherit MessageExtensions 


::method Init 
self~init:super(...) 
self~ConnectEditNotify("AMOUNT", "CHANGE") 


::method OnChange 
ec = self~GetEditControl ("AMOUNT") 
if ec^GetText^Space(0) \= "" & ec^GetText^DataType("N") = 0 then do 
ec~SetModified(0) 
ec^Select 
ec^ReplaceSelText ("0") 
end 


1. Connections are usually placed in the Init or InitDialog method. If both methods are defined, use 
init as the place for this connection - but not before init:super has been called. 


2. The event-handling methods receive two arguments: the ID of the edit control (extract the 
low-order word) and the handle to the edit control. 


Example: 


::method Handler 
use arg ev id, handle 
id = .DlgUtil^loWord(ev. id) 
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11.10. ConnectListBoxNotify 


>>-aMessageExtensions~ ConnectListBoxNotify (--id-- ,--"--+-DBLCLK----+--"--> 
+-ERRSPACE--+ 
+-GOTFOCUS--+ 
+-LOSTFOCUS-+ 
+-SELCANCEL-+ 
+-SELCHANGE-+ 


>--+--------------- 4--)------------------------------------------------- >< 
*-,--msgToRaise-* 


The ConnectListBoxNotify method connects a particular WM, NOTIFY message for a list box with a 
method. The WM. NOTIFY message informs the dialog that an event has occurred in the list box. 


Arguments: 


The arguments are: 
id 
The ID of the list box of which a notification is to be connected to a method. 


event 


The event to be connected with a method: 


DBLCLK 


An entry in the list box has been selected with a double click. 


ERRSPACE 


An out-of-memory problem has occurred. 


GOTFOCUS 


The list box got the input focus. 


LOSTFOCUS 


The list box lost the input focus. 


SELCANCEL 


The selection in the list box has been canceled. 
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SELCHANGE 


Another list box entry has been selected. 


msgToRaise 


The message that is to be sent whenever the specified notification is received from the list box. 
Provide a method with a matching name. If you omit this argument, the event is preceded by 
On. 


Return value: 


The return codes are: 


0 
No error detected. 
-1 
The resource ID could not be resolved or the event argument is incorrect. 
1 
The message was not connected correctly. 
Example: 


The following example displays the text of the selected list box entry: 


::class MyDlgClass subclass UserDialog inherit MessageExtensions 


::method Init 
self~init:super(...) 
self~ConnectListBoxNotify("MYLIST", "SELCHANGE", "SelectionChanged") 


::method SelectionChanged 
li = self~GetListBox ("MYLIST") 
say "New selection is:" li^Selected 


Notes: 


1. Connections are usually placed in the Init or InitDialog method. If both methods are defined, use 
init as the place for this connection - but not before init:super has been called. 


2. The event-handling methods receive two arguments: the ID of the list box (extract the low-order 
word) and the handle to the list box. Example: 


::method Handler 
use arg ev id, handle 
id = .DlgUtil^loWord(ev. id) 
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11.11. ConnectComboBoxNotify 


>>-aMessageExtensions~ ConnectComboBoxNotify (--id--,--"--4*-CHANGE------- pet 
*-UPDATE------- + 
*-CLOSEUP------ * 
*-DROPDOWN----- * 
*-DBLCLK------- * 
*-ERRSPACE----- * 
*-GOTFOCUS----- * 


*-LOSTFOCUS-----* 
*-SELCHANGE-----* 
*-SELENDOK----- * 
+-SELENDCANCEL-+ 


a ж) Ss SS Ss ees >< 


+-,--msgToRaise-+ 


The ConnectComboBoxNotify method connects a particular WM_NOTIFY message for a combo box 
with a method. The WM_NOTIFY message informs the dialog that an event has occurred in the combo 
box. 


Arguments: 


The arguments are: 


id 
The resource ID of the combo box for which a notification is to be connected to a method. 


event 


The event to be connected with a method: 


CHANGE 


The text in the edit control has been altered. This notification is sent after Windows 
updated the screen. 


UPDATE 


The text in the edit control has been altered. This notification is sent before Windows 
updates the screen. 


CLOSEUP 


The list of the combo box has been closed. 


DROPDOWN 


The list of the combo box is about to be made visible. 


DBLCLK 


An entry in the combo box list has been selected with a double click. 
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ERRSPACE 


An out-of-memory problem has occurred. 


GOTFOCUS 


The combo box got the input focus. 


LOSTFOCUS 


The combo box lost the input focus. 


SELCHANGE 


Another entry in the combo box list has been selected. 


SELENDOK 


The list was closed after another entry was selected. 


SELENDCANCEL 


After the selection of another entry, another control or dialog was selected, which 
canceled the selection of the entry. 


msgToRaise 


The message that is to be sent whenever the specified notification is received from the combo 
control. Provide a method with a matching name. If you omit this argument, the event is 
preceded by On. 


Return value: 


The return codes are: 


-1 
The resource ID could not be resolved or the event argument is incorrect. 
0 
No errors were detected. 
1 
The message was not connected correctly. 
Example: 


The following example invokes method PlaySong whenever the list of the combo box with the 
resource ID of PROFESSIONS is about to be made visible. In this case PROFESSIONS is a 
symbolic ID that has been added to the ConstDir directory of the MyDlgClass in another part of the 
program: 


::class MyDlgClass subclass UserDialog inherit MessageExtensions 


::method InitDialog 
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self~init:super(...) 
self~ConnectComboBoxNotify("PROFESSIONS", "DROPDOWN", "PlaySong") 


Notes: 


1. Connections are usually placed in the Init or InitDialog method. If both methods are defined, use 
init as the place for this connection - but not before init:super has been called. 


2. The event-handling methods receive two arguments: the first is a combination of the ID of the 
combo box and the ID of the notification messages. (Extract the low-order word to get the 
combo box ID.) The second argument is the window handle of the combo box. Example: 


::method PlaySong 
use arg eventID, handle 
id = .DlgUtil^loWord(eventID) 
if id -- self^ConstDir["PROFESSIONS"] then 
-- take some action 


11.12. ConnectScrollBarNotify 


»»-aMessageExtensions^ConnectScrollBarNotify (--id--,--"--4-UP-------- +--"--> 
+-DOWN------ + 
+-ТОРр======= + 


+-BOTTOM----+ 
+-PAGEUP----+ 
+-PAGEDOWN--+ 


+-ENDSCROLL-+ 
+-POSITION--+ 


>--+--------------- 4--)--------------------------------------------------- >< 


+-,--msgToRaise-+ 


The ConnectScrollBarNotify method connects a particular WM_NOTIFY message for a scroll bar with a 
method. The WM_NOTIFY message informs the dialog that an event has occurred with regard to the 
scroll bar. 


Arguments: 


The arguments are: 


id 


The ID of the scroll bar of which a notification is to be connected to a method. 


ooRexx OODialog Reference Version 4.0.0 469 


Chapter 11. MessageExtensions Class 


event 


The event to be connected with a method: 


UP 


The scroll bar was scrolled to the left or up by one unit. 


DOWN 


The scroll bar was scrolled to the right or down by one unit. 


TOP 


The scroll bar was scrolled to the upper left. 


BOTTOM 


The scroll bar was scrolled to the lower right. 


PAGEUP 


The scroll bar was scrolled to the left or up by one page size. 


PAGEDOWN 


The scroll bar was scrolled to the right or down by one page size. 


DRAG 
The scroll bar has been dragged. 


ENDSCROLL 


Scrolling has been ended, that is, the appropriate key or mouse button has been released. 


POSITION 


The scroll bar was scrolled to an absolute position (the left mouse button has been 
released). 


msgToRaise 


The message that is to be sent whenever the specified notification is received from the scroll 
bar. Provide a method with a matching name. If you omit this argument, the event is preceded 
by On. 


Return value: 


The return codes are: 


No error detected. 


The resource ID could not be resolved or the event argument is incorrect. 
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The messages was not connected correctly. 


Example: 


The following example connects the POSITION event with method OnPosition, which extracts the 
new position from the notification arguments and stores it for the scroll bar. It also displays the new 
position and the event type for POSITION, which is to be 4: 


::class MyDlgClass subclass UserDialog inherit MessageExtensions 


::method InitDialog 
self^InitDialog:super(...) 
self^ConnectScrollBarNotify ("MYSCROLL", "POSITION") 


::method OnPosition 
use arg ev pos, hnd 
pos = .DlgUtil^hiWord(ev. pos) 


-- redraw scroll bar with new position 
self^GetScrollBar("MYSCROLL")^setPos(pos,1) 


say "Pos:" pos 
say "Verify event code (should be 4):" .DlgUtil^loWord(ev. pos) 


1. The method can only be called after the scroll bar was created by Windows. A good location for 
this connection is the InitDialog method. 


2. The event-handling methods receive two arguments: an event-position pair and the handle to 
the scroll bar. You can retrieve the scroll bar position by extracting the high-order word. 


Example: 


::method Handler 
use arg ev pos, handle 
position - .DlgUtil^hiWord(ev. pos) 


If the user changed the scroll bar position, you must set the scroll bar position with setPos to 
keep the selected position. 


11.13. ConnectTabNotify 


»»-aMessageExtensions^ConnectTabNotify (--id--,--"---4-KEYDOWN----- dues» 
+-SELCHANGE---+ 
+-SELCHANGING-+ 


>--+--------------- 4--)----------------------------------------------- >< 
+-,--msgToRaise-+ 
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The ConnectTabNotify method connects a particular WM_NOTIFY message for a tab control with a 
method. The WM_NOTIFY message informs the dialog that an event has occurred with regard to the tab 


control. 


Arguments: 


The arguments are: 


id 
The ID of the tab control of which a notification is to be connected to a method. 
event 
The event to be connected with a method: 
KEYDOWN 
A key has been pressed while the tab control was focused. 
SELCHANGE 
Another tab has been selected in the tab control. This method is called after the selection 
was changed. 
SELCHANGING 
Another tab has been selected in the tab control. This method is called before the 
selection is changed. 
msgToRaise 


The message that is to be sent whenever the specified notification is received from the tab 
control. Provide a method with a matching name. If you omit this argument, the event is 


preceded by On. 


Return value: 


The return codes are: 


No error detected. 


The resource ID could not be resolved or the event argument is incorrect. 


The messages was not connected correctly. 
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Example: 


The following example invokes method OnSelChange whenever another tab is selected in the tab 
control PAGE: 


::class MyDlgClass subclass UserDialog inherit MessageExtensions 


::method Init 
self~init:super(...) 
self~ConnectTabNotify("PAGE", "SELCHANGE") 


Notes: 


1. Connections are usually placed in the Init or InitDialog method. If both methods are defined, use 
init as the place for this connection - but not before init:super has been called. 


2. The event-handling method that is connected to KEYDOWN receives two arguments: the control 
ID of the tab control and the virtual key code that has been pressed. Use the method KeyName 
of the VirtualKeyCodes class to get the name of the key. Note that your class must inherit from 
the VirtualKeyCodes class to use the KeyName method. Example: 


::method OnKeyDown 
use arg id, vkey 
say "Key" self^KeyName(vkey) "was pressed." 


3. All other event-handling methods receive two arguments: the ID of the tab control (extract the 
low-order word) and the handle to the tab control. Example: 


::method Handler 
use arg ev id, handle 
id = .DlgUtil^loWord(ev. id) 


11.14. ConnectSliderNotify 


»»-aMessageExtensions^ConnectSliderNotify (--id--,--"--4-UP------- Дора aS 
+-DOWN----- + 
+-Т0Р------ + 


+-ВОТТОМ---+ 
+-PAGEUP---+ 
+-PAGEDOWN-+ 


+-POSITION-+ 
+-ENDTRACK-+ 


a O E E в) наанаа >< 
+-,--msgToRaise-+ 
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The ConnectSliderNotify method connects a particular WM_NOTIFY message for a slider control, 
which is also called a track bar, with a method. The WM_NOTIFY message informs the dialog that an 
event has occurred with regard to the slider control. 


Arguments: 


The arguments are: 


id 
The ID of the slider control of which a notification is to be connected to a method. 


event 


The event to be connected with a method: 


UP 
The Up or right key has been pressed. 


DOWN 
The Down or left key has been pressed. 


TOP 
The Home key has been pressed. 


BOTTOM 
The End key has been pressed. 


PAGEUP 
The PgUp key has been pressed. 


PAGEDOWN 
The PgDn key has been pressed. 


DRAG 


The slider has been moved. 


POSITION 


The left mouse button has been released, following a DRAG notification. 


ENDTRACK 


The slider movement is completed, that is, the appropriate key or mouse button has been 


released. 
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msgToRaise 


The message that is to be sent whenever the specified notification is received from the slider 
control. Provide a method with a matching name. If you omit this argument, the event is 
preceded by On. 


Return value: 


The return codes are: 


0 
No error detected. 
-1 
The resource ID could not be resolved or the event argument is incorrect. 
1 
The messages was not connected correctly. 
Example: 


The following example connects the POSITION event (release mouse button after dragging) with 
method PosSet, which extracts the new slider position from the notification arguments and displays 
it together with the event type for POSITION, which should be 4: 


::class MyDlgClass subclass UserDialog inherit MessageExtensions 


::method InitDialog 
self^InitDialog:super(...) 
self^ConnectSliderNotify ("MYSLIDER", "POSITION", PosSet) 


::method PosSet 
use arg ev pos, hnd 
pos = .DlgUtil^hiWord(ev. pos) 


say "Verify event code (should be 4):" .DlgUtil^loWord(ev. pos) 
Notes: 


1. The method can only be called after the slider was created by Windows. A good location for this 
connection is the InitDialog method. 


2. The event-handling methods receive two arguments: an event-position pair and the handle to 
the slider control. For some events, you can retrieve the slider position by extracting the 
high-oder word. Example: 


::method Handler 
use arg ev pos, handle 
position - .DlgUtil^hiWord(ev. pos) 
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The AdvancedControls class provides methods to add and use the Win32 controls tree view control, list 
view control, tab control, slider control, and progress bar. It also provides methods to retrieve a specific 
object for any dialog control. 


To use the methods defined by this mixin class, you must inherit from this class by specifying the 
INHERIT option for the ::CLASS directive in the class declaration. For example: 


::class NewWin32Dialog SUBCLASS UserDialog INHERIT AdvancedControls 


Requires: 
The AdvancedControls class requires the class definition file oodwin32.cls: 
::requires oodwin32.cls 

Methods: 


Instances of the AdvancedControls class implement the methods listed in the AdvancedControls 
Instance Methods table. 


Table 12-1. AdvancedControls Instance Methods 




































































Method... ..оп page 
AddListControl AddListControl 
addProgressBar addProgressBar 
AddSliderControl AddSliderControl 
AddTabControl AddTabControl 
AddTreeControl AddTreeControl 
ConnectListControl ConnectListControl 
ConnectSliderControl ConnectSliderControl 
ConnectTreeControl ConnectTreeControl 
GetButtonControl GetButtonControl 
GetCheckControl GetCheckControl 
GetComboBox GetComboBox 
GetEditControl GetEditControl 
getGroupBox getGroupBox 
GetListBox GetListBox 
GetListControl GetListControl 
getProgressBar getProgressBar 
GetRadioControl GetRadioControl 
GetScrollBar GetScrollBar 
GetSliderControl GetSliderControl 
GetStaticControl GetStaticControl 
GetTabControl GetTabControl 
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Method... ..оп page 





GetTreeControl GetTreeControl 














12.1. GetStaticControl 


»»-anAdvancedControl^GetStaticControl(--id--4------------- +--)->< 


+-,--сатерогу-+ 


The GetStaticControl method returns an object of the StaticControl class that is assigned to Ше static 
dialog item with the specified ID. The StaticControl class provides methods to query and manipulate 
static dialog items like static text, group boxes, or frames. The static controls must have a positive ID. 


Arguments: 


The arguments are: 
id 
The ID of the static dialog item. 


category 


The number of the category dialog page containing the requested dialog item. This argument 
must only be specified for category dialogs. 


Return value: 


An object of the StaticControl class or .Nil if the requested dialog item does not exist. 


Example: 


The following example requests an object of dialog item ITEM7 and, if the dialog item exists, 
resizes it, changes the displayed text, and sets another background and foreground color: 


::class MyDlgClass subclass UserDialog inherit AdvancedControls 


::method ReArrange 
di = self~GetStaticControl ("ITEM7") 
if di == .Nil then return 
di^Resize(100, 25, "HIDE") 
di^Title-"Processing layout update!" 
di^SetColor(7,4) 
di^Show 


Note: GetStaticControl connects an Object Rexx object with a Windows object. If the object does not 
exist, the Nil object is returned. Therefore, this method can only be applied after the Windows dialog 
has been created (after the invocation of Startlt). 
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12.2. GetEditControl 


»»-anAdvancedControl^GetEditControl(--id--4------------- +--)--->< 


*t-,--category--t 


The GetEditControl method returns an object of the EditControl class that is assigned to the entry line 
with the specified ID. The EditControl class (see EditControl Class) provides methods to query and 
manipulate edit controls. 


Arguments: 


The arguments are: 
id 

The ID of the edit control. 
category 


The number of the category dialog page containing the requested edit control. This argument 
must only be specified for category dialogs. 


Return value: 


An object of the StaticControl class or .Nil if the requested edit control does not exist. 


Example: 


The following example gets an object of the EditControl class and checks whether the NAME entry 
line is empty. If the name field is empty, the dialog is not valid. 


::class MyDlgClass subclass UserDialog inherit AdvancedControls 
: :method Validate 
di = self^GetEditControl("NAME") 


if di == .Nil then return 0 
if di^Title^space(0) \="" then return 1 


Note: GetEditControl connects an Object Rexx object with a Windows object. If the object does not 
exist, the Nil object is returned. Therefore, this method can only be applied after the Windows dialog 
has been created (after the invocation of Startlt). 


12.3. GetButtonControl 


»»-anAdvancedControl^GetButtonControl(--id--4------------- +--)->< 


+-,--category-+ 
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The GetButtonControl method returns an object of the ButtonControl class that is assigned to the push 
button with the specified ID. The ButtonControl class (see ButtonControl Class) provides methods to 
query and manipulate push buttons. 

Arguments: 


The arguments are: 
id 
The ID of the push button. 
category 
The number of the category dialog page containing the requested push button. This argument 
must only be specified for category dialogs. 
Return value: 
An object of the ButtonControl class or .Nil if the requested push button does not exist. 
Example: 


The following example displays the current state of the OK button by retrieving an object of the 
Button class and calling the State method: 


::class MyDlgClass subclass UserDialog inherit AdvancedControls 


::method CurrentState 
di = self~GetButtonControl (1) 
if di == .Nil then return 0 
say "State is" di^State 


Note: GetButtonControl connects an Object Rexx object with a Windows object. If the object does 
not exist, the Nil object is returned. Therefore, this method can only be applied after the Windows 
dialog has been created (after the invocation of Startlt). 


12.4. GetRadioControl 


»»-anAdvancedControl^GetRadioControl(--id--4------------- +--)-->< 


+-,--category-+ 


The GetRadioControl method returns an object of the RadioButton class that is assigned to the radio 


button with the specified ID. The RadioButton class (see RadioButton Class) provides methods to query 
and manipulate radio buttons. 
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Arguments: 


The arguments are: 
id 

The ID of the radio button. 
category 


The number of the category dialog page containing the requested radio button. This argument 
must only be specified for category dialogs. 


Return value: 


An object of the RadioButton class or .Nil if the requested radio button does not exist. 


Example: 


The following example displays a message when radio button CHOICE] is selected: 


::class MyDlgClass subclass UserDialog inherit AdvancedControls 


::method CurrentState 
di = self^GetRadioControl("CHOICE1") 
if di == .Nil then return 0 
if di^checked then say "The radio button is selected!" 


Note: GetRadioControl connects an Object Rexx object with a Windows object. If the object does not 
exist, the Nil object is returned. Therefore, this method can only be applied after the Windows dialog 
has been created (after the invocation of Startlt). 


12.5. GetCheckControl 


»»-anAdvancedControl^GetCheckControl(--id--4------------- +--)-->< 


+-,--category-+ 


The GetCheckControl method returns an object of the CheckBox class that is assigned to the check box 
with the specified ID. The CheckBox class (see CheckBox Class) provides methods to query and 
manipulate check boxes. 


Arguments: 


The arguments are: 


id 
The ID of the check box. 


ooRexx OODialog Reference Version 4.0.0 481 


Chapter 12. AdvancedControls Class 


category 


The number of the category dialog page containing the requested check box. This argument 
must only be specified for category dialogs. 


Return value: 
An object of the CheckBox class or .Nil if the requested check box does not exist. 
Example: 


The following example displays a message when check box CHOICE is checked: 


::class MyDlgClass subclass UserDialog inherit AdvancedControls 


::method CurrentState 
di = self~GetCheckControl ("СНОІСЕ1") 
if di == .Nil then return 0 
if di^checked then say "The check box is checked!" 


Note: GetCheckControl connects an Object Rexx object with a Windows object. If the object does 
not exist, the Nil object is returned. Therefore, this method can only be applied after the Windows 
dialog has been created (after the invocation of Startlt). 


12.6. getGroupBox 


»»-anAdvancedControl^getGroupBox(--id--4------------- *--)------ >< 


+-,--category-+ 


The getGroupBox method returns an object of the GroupBox class that represents the group box with the 
specified resource ID. See the GroupBox Class for more detail on group boxes. 


Arguments: 


The arguments are: 
id 

The resource ID of the group box. 
category 


The number of the category dialog page containing the requested group box. This argument 
must only be specified for category dialogs. 


Return value: 


A GroupBox object or .Nil if the underlying Windows group box control does not exist. 
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Example: 


The following example shows how the text (label) of a group box could be changed during program 
execution: 
::class MyPhoneBook subclass ResDialog inherit AdvancedControls 
::method onUseFull 

gb = self^getGroupBox(IDC. GB. TELEPHONE) 

chkBox = self^getCheckBox(IDC, CHK USE, FULL) 

if chkBox^checked then do 

gb~setTitle("Phone Numbers (including area code)") 
end 
else do 


gb^setTitle("Phone Numbers") 
end 


Note: getGroupBox connects the ooDialog object with a Windows control. If the control does not 
exist, this connection can not be made. Therefore, this method should only be used after the 
Windows dialog has been created. In initDialog() or at some point in the life cycle of the dialog after 
initDialog(). 


12.7. GetListBox 


»»-anAdvancedControl^GetListBox(--id--4------------- +--)------- >< 
+-,т-сатерогу-+ 


The GetListBox method returns an object of the ListBox class that is assigned to the list box with the 
specified ID. The ListBox class (see ListBox Class) provides methods to query and manipulate list boxes. 


Arguments: 


The arguments are: 
id 
The ID of the list box. 


category 


The number of the category dialog page containing the requested list box. This argument must 
only be specified for category dialogs. 


Return value: 


An object of the ListBox class or .Nil if the requested list box does not exist. 
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Example: 


The following example removes all entries of list box AREAS and adds several new entries. Entry 
City will be preselected. Object "di" is connected to list box AREAS. 


::class MyDlgClass subclass UserDialog inherit AdvancedControls 


::method UpdateList 
di = self~GetListBox ("AREAS") 
if di == .Nil then return 0 
di^DeleteAll 
di^Add("Town") 
di^Add("City") 
di^Add("Green") 
di^Add("Forest") 
di~Select ("City") 


Note: GetListBox connects an Object Rexx object with a Windows object. If the object does not exist, 
the Nil object is returned. Therefore, this method can only be applied after the Windows dialog has 
been created (after the invocation of Startlt). 


12.8. GetComboBox 


»»-anAdvancedControl^GetComboBox(--id--4------------- *--)------ >< 


+-,--category-+ 


The GetComboBox method returns an object of the ComboBox class that is assigned to the list box with 
the specified ID. The ComboBox class (see ComboBox Class) provides methods to query and 
manipulate combo boxes. 


Arguments: 


The arguments are: 
id 
The ID of the combo box. 


category 


The number of the category dialog page containing the requested combo box. This argument 
must only be specified for category dialogs. 


Return value: 


An object of the ComboBox class or .Nil if the requested combo box does not exist. 
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Example: 


The following example comes from a fictious accounting program. In one of the dialogs for the 
program, when the user selects a specific city, say San Diego, the zip code combo box is populated 
with the valid zip codes for that city. In the program, symbolic IDs have been used for the controls. 
The valid zip codes are passed into the method as an array. 


::class "BillingDlg" subclass RcDialog inherit AdvancedControls MessageExtensions 


::method setZipCodes 
use strict arg codes 


combo = self^getComboBox(IDC. COMBO, ZIP) 
if combo == .Nil then return .false 


lowest - 99999 
combo^deleteAll 
do zipCode over codes 
combo^add(zipCode) 
if zipCode « lowest then do 
lowest - zipCode 
end 
end 
combo^select (lowest) 
return .true 


Note: GetComboBox connects an Object Rexx object with a Windows object. If the object does not 
exist, the Nil object is returned. Therefore, this method can only be applied after the Windows dialog 
has been created (after the invocation of Startlt). 


12.9. GetScrollBar 


»»-anAdvancedControl^GetScrollBar(--id--4------------- +--)----- >< 


*-,--category--* 


The GetScrollBar method returns an object of the ScrollBar class that is assigned to the scroll bar with 
the specified ID. The ScrollBar class (see ScrollBar Class) provides methods to query and manipulate 
scroll bars. 


Arguments: 


The arguments are: 


id 
The ID of the scroll bar. 
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category 
The number of the category dialog page containing the requested scroll bar. This argument 
must only be specified for category dialogs. 
Return value: 


An object of the ScrollBar class or .Nil if the requested scroll bar does not exist. 


Example: 


The following example sets a new range and a new position for scroll bar HORSB. Object "di" is 
connected to scroll bar HORSB. 


::class MyDlgClass subclass UserDialog inherit AdvancedControls 


::method FocusPage 
di = self^GetScrollBar("HORSB") 
if di == .Nil then return 0 
di~setRange(0, 1000, 0) 
di~setPos(500, 1) 


Note: GetScrollBar connects an Object Rexx object with a Windows object. If the object does not 
exist, the Nil object is returned. Therefore, this method can only be applied after the Windows dialog 
has been created (after the invocation of Startlt). 


12.10. GetTreeControl 


»»-anAdvancedControl^GetTreeControl(--id--4------------- +--)--->< 


+- ,--саїерогу-+ 


The GetTreeControl method returns an object of the TreeControl class that is assigned to the tree view 
with the specified ID. The TreeControl class (see TreeControl Class) provides methods to query and 
manipulate tree views. 
Arguments: 

The arguments are: 

id 

The ID of the tree view. 
category 


The number of the category dialog page containing the requested tree view. This argument 
must only be specified for category dialogs. 
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Return value: 


An object of the TreeControl class or .Nil if the requested tree view does not exist. 


Example: 


The following example initializes tree view 101 by sending message ADD to object "tc", which is 
assigned to 101 by using GetTreeControl: 


::class MyDlgClass subclass UserDialog inherit AdvancedControls 


::method InitDialog 
tc = self~GetTreeControl (101) 
if tc == .Nil then return 
tc^Add("Root 1") 


tc^Add( ,"Item 1") 
tc^Add( ,"Item 2") 
tc^Add( ,"Item 3") 
tc^Add("Root 2", , ,"EXPANDED") 
tc^Add( ,"Item 4", , ,"BOLD") 


tc^Add( ,"Item 5") 
tc^Add( ,"Subroot") 
tc^Add( , ,"Item 6",3) 


Note: GetTreeControl connects an Object Rexx object with a Windows object. If the object does not 
exist, the Nil object is returned. Therefore, this method can only be applied after the Windows dialog 
has been created (after the invocation of Startlt). 


12.11. GetListControl 


»»-anAdvancedControl^GetListControl(--id--4------------- +--)--->< 
+-,--category-+ 


The GetListControl method returns an object of the ListControl class that is assigned to the list view with 
the specified ID. The ListControl class (see ListControl Class) provides methods to query and 
manipulate list views. 


Arguments: 


The arguments are: 
id 
The ID of the list view. 


category 


The number of the category dialog page containing the requested list view. This argument must 
only be specified for category dialogs. 
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Return value: 


An object of the ListControl class or .Nil if the requested list view does not exist. 


Example: 


The following example initializes list view 101 by sending message ADD to object Ic, which is 
assigned to 101 by using GetListControl: 


::class MyDlgClass subclass UserDialog inherit AdvancedControls 


::method InitDialog 
1с = self~GetListControl (101) 
if 1с == .Nil then return 
1c^^Add(101222)^^Add(,"Smith")^^Add(, ,"John") 
1c^^Add(101223)^^Add(,"Michael")^^Add(, ,"Carl") 


Note: GetListControl connects an Object Rexx object with a Windows object. If the object does not 
exist, the Nil object is returned. Therefore, this method can only be applied after the Windows dialog 
has been created (after the invocation of Startlt). 


12.12. getProgressBar 


»»-anAdvancedControl^getProgressBar(--id--4------------- $c-)---5« 


*-,--category--t 


The getProgressBar method returns an object of the ProgressBar Control class that is assigned to the 
progress bar with the specified ID. The ProgressBar class (see ProgressBar Class) provides methods to 
query and manipulate progress bars. 


Arguments: 


The arguments are: 
id 
The ID of the progress bar. 


category 


The number of the category dialog page containing the requested progress bar. This argument 
must only be specified for category dialogs. 


Return value: 


An object of the ProgressBar class or .Nil if the requested progress bar does not exist. 
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Example: 


The following example initializes and modifies progress bar PROGRESS by sending messages to 
the object that is returned by GetProgressBar: 


::class MyDlgClass subclass UserDialog inherit AdvancedControls 


::method InitDialog 
pb = self~getProgressBar ("PROGRESS") 
if pb == .Nil then return 
pb^setstep(50) 
pb^setrange(,500) 


::method UpdateProgress 
use arg amount 
self~getProgressBar ("PROGRESS") ~setPos (amount) 


Note: getProgressBar connects an Object Rexx object with a Windows object. If the object does not 
exist, the Nil object is returned. Therefore, this method can only be applied after the Windows dialog 
has been created (after the invocation of Startlt). 


12.13. GetSliderControl 


»»-anAdvancedControl^GetSliderControl(--id--4------------- +--)->< 
t*t-,--category-* 


The GetSliderControl method returns an object of the SliderControl class that is assigned to the track bar 
with the specified ID. The SliderControl class (see SliderControl Class) provides methods to query and 
manipulate track bars. 


Arguments: 


The arguments are: 
id 
The ID of the track bar. 


category 


The number of the category dialog page containing the requested track bar. This argument 
must only be specified for category dialogs. 


Return value: 


An object of the SliderControl class or .Nil if the requested track bar does not exist. 
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Example: 
The following example initializes track bar 103: 
::class MyDlgClass subclass UserDialog inherit AdvancedControls 
::method InitTheSlider 
sl = self~GetSliderControl (103) 
if sl == .Nil then return 
no = 0; yes = 1 
Sl^ClearSelRange (no) 
sl^SetMax(200,no) 
Sl^SetTickFrequency (50) 
Sl^SetTickAt (75) 
sl^SetSelStart(20, no) 


Sl^SetSelEnd(180, yes) 
sl^Pos - 167 


Note: GetSliderControl connects an Object Rexx object with a Windows object. If the object does not 
exist, the Nil object is returned. Therefore, this method can only be applied after the Windows dialog 
has been created (after the invocation of Startlt). 


12.14. GetTabControl 


»»-anAdvancedControl^GetTabControl(--id--4------------- +--)---->< 
+-,--category-+ 


The GetTabControl method returns an object of the TabControl class that is assigned to the tab control 
with the specified ID. The TabControl class (see TabControl Class) provides methods to query and 
manipulate tab controls. 


Arguments: 


The arguments are: 
id 
The ID of the tab control. 


category 


The number of the category dialog page containing the requested tab control. This argument 
must only be specified for category dialogs. 


Return value: 


An object of the TabControl class or .Nil if the requested tab control does not exist. 
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Example: 
The following example initializes tab control PAGES to have five tabs: 
::class MyDlgClass subclass UserDialog inherit AdvancedControls 
::method InitDialog 


self~GetTabControl ("PAGES") ~AddSequence("Design","Implementation", , 
"Test", "Review", "Release" ) 


Note: GetTabControl connects an Object Rexx object with a Windows object. If the object does not 
exist, the Nil object is returned. Therefore, this method can only be applied after the Windows dialog 
has been created (after the invocation of Startlt). 


12.15. ConnectTreeControl 


»»-anAdvancedControl^ConnectTreeControl(--id--4------------------ +--)->< 
+-,--attributeName-+ 


The ConnectTreeControl method creates a new attribute and connects it to the tree view id. The attribute 
has to be synchronized manually with the tree view. You can do this globally using the SetData and 
GetData methods or methods provided by the TreeControl class. A tree view can contain many items. 
When the dialog data is set, the first tree view item containing the same text as the text stored in the 
connected attribute, is selected. When the data is received, the attribute receives the text of the selected 
tree view item. Usually, the connection is made automatically and you do not have to use this method. 


Arguments: 


The arguments are: 


id 
The ID of the tree view that you want to connect. 


attributeName 


An unused valid Rexx symbol because an attribute with exactly this name is added to the 
dialog object by this method. Blank spaces, ampersands (&), and colons (:) are removed from 
the attributeName. 


If this argument is omitted, is not valid, or already exists, the following occurs: 


* Ifthe ID is numeric, an attribute with the name DATAid is used, where id is the value of the 
first argument. 


* Ifthe ID is symbolic, the attribute is named as the ID. 
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Example: 


In the following example, the tree view with ID 202 is associated with the attribute FileName. Then 
TEST.REX is assigned to the newly created attribute. Then the dialog is executed, which preselects 
TEST.REX in the tree view, if it exits. After the dialog is terminated, the selected entry of the tree 
view is copied to the attribute FileName. 


MyDialog~ConnectTreeControl(202, "FileName") 
MyDialog^FileName-"TEST.REX" 
MyDialog^Execute("SHOWTOP") 

say MyDialog~FileName 


12.16. ConnectListControl 


»»-anAdvancedControl^ConnectListControl(--id--4------------------ +--)->< 
+-,--attributeName-+ 


The ConnectListControl method creates a new attribute and connects it to the list view id. The 
attributeName is a string containing the numbers of the selected lines. The numbers are separated by 
blanks. Therefore, if value of the attribute after GetData is "3 5 6", the third, fifth, and sixth items are 
currently selected, or will be selected when SetData is executed. For further information, refer to 
ConnectTreeControl. 


Example: 


In the following example, the list view with ID 202 is associated with the attribute Customers. The 
first, 14th, and 29th entries in the list are preselected. 


MyDialog^ConnectListContro1(202, "Customers") 
MyDialog^Customers-"1 14 29" 


12.17. ConnectSliderControl 


»»-anAdvancedControl^ConnectSliderControl(--id--4------------------ +--)->< 
+-,--attributeName-+ 


The ConnectSliderControl method creates a new attribute and connects it to the track bar id. The 
attributeName is the numerical position of the slider. For further information, refer to 
ConnectTreeControl. 


12.18. ConnectTabControl 


»»-anAdvancedControl^ConnectTabControl(--id--4------------------ +--)->< 
+-,--attributeName-+ 
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The ConnectTabControl method creates a new attribute and connects it to the tab control id. The 
attributeName is the text of the active tab. For further information, refer to ConnectTreeControl. 


12.19. AddTreeControl 


»»-anAdvancedControl^AddTreeControl(--id--,--4--------- 


uid == ЕД nur iam > ==у==> 


+-attributeName-+ 


»--,--CX--,--Cy--*-------------------------------- So a >< 
| +----------------< + | 
| V | | 
+-,--"----+-ATROOT--------+-+--"-+ 

*-BUTTONS------- * 
*-LINES--------- * 
*-EDIT---------- * 
*-HSCROLL------- * 
*-VSCROLL------- * 
+-SHOWSELALWAYS-+ 
EeADDee——---- * 
*-NODRAG-------- * 
*-GROUP--------- * 
*-HIDDEN-------- * 
*-NOTAB--------- * 
*-NOBORDER------ + 


The AddTreeControl method adds a tree view to the dialog and connects it with a data attribute. For 
further information on tree view controls, refer to TreeControl Class. 


Arguments: 


The arguments are: 


id 


A unique identifier assigned to the control. You need the ID to refer to this control in other 


methods. 


attributeName 


The name of the data attribute associated with the dialog item. See attributeName to get 
information on what happens when this argument is omitted. 


х,у 


The position of the upper left corner of the control relative to the dialog, in dialog units. 


CX, ху 


The width and height of the dialog item, in dialog units. 
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options 
This argument determines the behavior and style of the dialog item and can be one or more of 


the following, separated by blanks: 


ATROOT 


The tree view has lines linking child items to the root of the hierarchy. 


BUTTONS 


The tree view adds a button to the left of each parent item. 


LINES 


The tree view has lines linking child items to their corresponding parent items. 


EDIT 


The tree view allows the user to edit the labels of tree view items. To store the edited text, 
you must connect a method to the ENDEDIT notification or connect the DEFAULTEDIT 
event handler (see ConnectTreeNotify). 


HSCROLL 


The tree view supports a horizontal scroll bar. 


VSCROLL 


The tree view supports a vertical scroll bar. 


SHOWSELALWAYS 


A selected item remains selected when the tree view loses focus. 


ALL 


The options ATROOT, BUTTONS, LINES, EDIT, HSCROLL, and SHOWSELALWAYS 
are all applied. 


NODRAG 


The tree view is prevented from sending "begin drag" notifications. 


GROUP 


The first control of a group of controls in which the user can move from one control to the 
next with the arrow key. 


HIDDEN 


The control is initially hidden. 


NOTAB 


The tab key cannot be used to move to this control. 
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No border is drawn around the control. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


The following example creates a tree view at position x=100 and y=80 and with a size of width=40 
and height=120. The ID of the tree is 555 and its data is associated with attribute BRANCH. The 
tree view uses lines for child items and roots, displays a button to the left of each parent item, and 


supports item editing. 


MyDialog^AddTreeControl(555, "Branch", 100, 80, 40, 120, , 
"LINES BUTTON EDIT ATROOT") 


12.20. AddListControl 


»»-anAdvancedControl^AddListControl(--id--, 


+--------------- +--,--х,--у--> 
+-attributeName-+ 


»--,--CX--,--Cy--*-------------------------------- 4--)------------------- >< 
| +------------------- + | 
| V | | 
*-,--"----4-ICOUN---------- +-+--"-+ 

*-SMALLICON----- + 
*-LIST---------- * 
*-REPORT-------- * 
*-ALIGNLEFT----- + 
*-ALIGNTOP------ + 
*-AUTOARRANGE----* 
*-ASCENDING----- + 
+-DESCENDING----+ 
*-EDIT---------- * 
*-HSCROLL------- * 
*-VSCROLL------- * 
*-NOSCROLL------ + 
*-NOHEADER------ + 
+-NOSORTHEADER--+ 
*-NOWRAP-------- * 
*-SINGLESEL----- + 
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+-SHAREIMAGES---+ 


+-GROUP--------- + 
+-HIDDEN-------- + 
*-NOTAB--------- * 
*-NOBORDER------ + 


The AddListControl method adds a list view to the dialog and connects it with a data attribute. For 
further information on list view controls, refer to ListControl Class. 


Arguments: 


The arguments are: 


id 
A unique identifier assigned to the control. You need the ID to refer to this control in other 
methods. 
attributeName 
The name of the data attribute associated with the dialog item. See ConnectTreeControl to get 
information on what happens when this argument is omitted. 
х,у 
The position of the upper left corner of the control relative to the dialog, in dialog units. 
CX, ху 
The width and height of the dialog item, in dialog units. 
options 


This argument determines the behavior and style of the dialog item and can be one or more of 
the following, separated by blanks: 


ICON 


Use the icon view. Each item appears as a full-sized icon with a label below it. The user 
can drag the items to any location in the list view control. 


SMALLICON 


Use the small-icon view. Each item appears as a small icon with a label to the right of it. 
The user can drag the items to any location in the list view control. 


LIST 


Use the list view. Each item appears as a small icon with a label to the right of it. Items 
are arranged in columns and cannot be moved by the user. 
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REPORT 


Use the report view. Each item appears on a separate line with information arranged in 
columns. The leftmost column contains the small icon and label, and subsequent columns 
contain subitems. 


ALIGNLEFT 


In icon and small-icon views, the items are left-aligned. 


ALIGNTOP 


In icon and small-icon views, the items are aligned with the top of the control. 


AUTOARRANGE 


In icon and small-icon views, the icons are always automatically arranged. 


ASCENDING 


Sorts items by item text in ascending order. 


DESCENDING 


Sorts items by item text in descending order. 


EDIT 


The list view allows the user to edit the list view items. To store the edited text, you must 
connect a method to the ENDEDIT notification or you connect the DEFAULTEDIT event 
handler (see ConnectTreeNotify). 


HSCROLL 


The list view supports a horizontal scroll bar. 


VSCROLL 


The list view supports a vertical scroll bar. 


NOSCROLL 


Disables scrolling. 


NOHEADER 


No column header is displayed in the report view. By default, columns have headers in the 
report view. 


NOSORTHEADER 


Specifies that column headers do not work like buttons. This option is useful if clicking a 
header in the report view does not carry out an action. 


NOWRAP 


Displays item text on a single line in the icon view. By default, the item text can wrap in 
the icon view. 
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SINGLESEL 


Allows only one item to be selected at a time. By default, several items can be selected. 


SHOWSELALWAYS 


Specifies that a selected item remains selected when the list view loses focus. 


DEFAULTEDIT 


Connects the notification that label editing has been started and ended with a predefined 
event-handling method. This method extracts the newly entered text from the notification 
and modifies the item of which the label was edited. If this event is not connected you 
must provide your own event-handling method and connect it with the BEGINEDIT and 
ENDEDIT events. Otherwise, the edited text is lost and the item remains unchanged. 


SHAREIMAGES 


The control does not take ownership of the image lists assigned to it. This option enables 
an image list to be used with several list controls. 


GROUP 


Specifies the first control of a group of control in which the user can move from one 
control to the next with the arrow keys. 


HIDDEN 


The control is initially hidden. 


NOTAB 


The tab key cannot be used to move to this control. 


NOBORDER 


No border is drawn around the control. 


Return value: 


The possible return values are: 


Success. 
less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


The following example creates a list view at position x=100 and y=80 and with a size of width=40 
and height=120. The list view with ID 555 is a report view with items sorted in ascending order. It 
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supports item editing and column headers do not behave like buttons. Its data is associated with 
attribute EMPLOYEES. 


MyDialog^AddListControl(555, "EMPLOYEES", 100, 80, 40, 120, , 
"REPORT ASCENDING EDIT NOSORTHEADER" ) 


12.21. addProgressBar 


»»--addProgressBar(--id--,--x--,--y--,--cx--,--cy-*----------- 4--)------------- >< 
+--,-style--t+ 


The addProgressBar method adds a progress bar to the dialog and connects it with a data attribute. For 
further information on progress bar controls, refer to ProgressBar Class. 


Arguments: 


The arguments are: 
id 
The resource ID for the progress bar. 


X, y, CX, Cy 


The control coordinates. 


style 
A list of 0 or more of the following style keywords separated by spaces. 


VERTICAL HIDDEN GROUP 
SMOOTH DISABLED ТАВ 
MARQUEE BORDER 


VERTICAL 


The progress bar is orientated vertically. The default orientation is horizontal. 


SMOOTH 


The progress is displayed in a smooth scrolling bar rather than the default segmented bar. 
This style is only displayed when Windows classic theme is in effect. All other themes 
over-ride this style. 


MARQUEE 


The progress bar moves like a marquee. This method requires Common Control Library 
version 6.0 or later. 


HIDDEN 


The not visible window style. 
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DISABLED 


The not enabled window style. 


BORDER 


The border window style. 


GROUP 
The group control style. 


TAB 


The tabstop control style. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


The following example creates a progress bar with ID DONE at the bottom of the dialog. The 


progress bar is as wide as the dialog. 


MyDialog^addProgressBar("DONE",10,MyDialog^sizey-16,MyDialog^sizex-20,12) 


12.22. AddSliderControl 


»»-anAdvancedControl^AddSliderControl(--id--,--4--------------- Кер 


>--,--у--р--ех----су--+----------------- 
| +-------------------- 


| ү 


+-attributeName-+ 


--------- +--)---------->< 


+- ,--"----+-AUTOTICKS------+-+--"-+ 


+-NOTICKS 


500 
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+-ВОТНЕ----------- + 
+-ENABLESELRANGE-+ 
+-GROUP---------- + 
*-HIDDEN--------- * 
SzNOTAB----------— * 
*-NOBORDER------- * 


The AddSliderControl method adds a slider control (track bar) to the dialog and connects it with a data 
attribute. For further information on slider controls, refer to SliderControl Class. 


Arguments: 


The arguments are: 


id 
A unique identifier assigned to the control. You need the ID to refer to this control in other 
methods. 
attributeName 
The name of the data attribute associated with the dialog item. See attributeName to get 
information on what happens when this argument is omitted. 
X,y 
The position of the upper left corner of the control relative to the dialog, in dialog units. 
Cx, Xy 
The width and height of the dialog item, in dialog units. 
options 


This argument determines the behavior and style of the dialog item and can be one or more of 
the following: 


AUTOTICKS 


Creates a slider that has a tick mark for each increment in its range of values. These tick 
marks are automatically added when an application calls the InitRange method. You 
cannot use the SetTickAt and SetTickFrequency methods to specify the position of the 
tick marks when you use this option. 


NOTICKS 


Creates a slider that does not display tick marks. 


HORIZONTAL 


Orients the slider horizontally. This is the default orientation. 


VERTICAL 


Orients the slider vertically. 
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TOP 


Displays tick marks along the top of a horizontal slider. 


BOTTOM 


Displays tick marks along the bottom of a horizontal slider. This option can be used 
together with the TOP option to display tick marks on both sides of the slider control. 


LEFT 


Displays tick marks along the left of a vertical slider. 


RIGHT 


Displays tick marks along the right of a vertical slider. This option can be used together 
with the LEFT option to display tick marks on both sides of the slider control. 


BOTH 


Displays tick marks on both sides of the slider in any direction. 


ENABLESELRANGE 


Displays a selection range. If you set this option, the tick marks at the starting and ending 
positions of a selection range are displayed as triangles and the selection range is 
highlighted. This can be used, for example, to indicate a preferred selection. 


GROUP 


Specifies the first control of a group of control in which the user can move from one 
control to the next with the arrow keys. 


HIDDEN 


The control is initially hidden. 


NOTAB 


The tab key cannot be used to move to this control. 


NOBORDER 


No border is drawn around the control. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 
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Example: 


The following example creates a vertical slider control at the right border of the dialog. The slider 
with ID PRESSURE displays automatic tick marks on both sides. Its position is associated with 
attribute PRESSURE. 


MyDialog^AddSliderControl("PRESSURE", , MyDialog^sizeX-30, 15, 20, , 
MyDialog^sizeY-30, "VERTICAL BOTH AUTOTICKS") 


12.23. AddTabControl 


»»-anAdvancedControl^AddTabControl(--id--,--4--------------- +--,--х--> 
+-attributeName-+ 


эу чех --су--#-----------<-----------------< +--)---------- >< 
| +----------------- + | 
| ү | | 
*-,--"----t-ALIGNRIGHT---4-4--"--4 
*-BUTTONS----- + 
+-FIXED------- + 


+-FOCUSNEVER--+ 
+-FOCUSONDOWN-+ 
+-ICONLEFT----+ 
+-LABELLEFT---+ 
+-MULTILINE---+ 


+-GROUP------- + 
+-HIDDEN------ + 
*-NOTAB------- * 


+-NOBORDER----+ 


The AddTabControl method adds a tab control to the dialog and connects it with a data attribute. For 
further information on tab controls, refer to TabControl Class. 


Arguments: 


The arguments are: 


id 
A unique identifier assigned to the control. You need the ID to refer to this control in other 
methods. 

attributeName 


The name of the data attribute associated with the dialog item. See ConnectTreeControl to get 
information on what happens when this argument is omitted. 


х,у 


The position of the upper left corner of the control relative to the dialog, in dialog units. 
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CX, ху 
The width and height of the dialog item, in dialog units. 

options 
This argument determines the behavior and style of the dialog item and can be one or more of 


the following: 


ALIGNRIGHT 


Right-justifies tabs. By default, tabs are left-justified within a row. 


BUTTONS 


Modifies the appearance of the tabs to look like buttons. 


FIXED 
Makes all tabs equal in width. You cannot use this option with the ALIGNRIGHT option. 


FOCUSNEVER 


A tab never receives the input focus. 


FOCUSONDOWN 
A tab receives the input focus when clicked (typically with option BUTTONS). 


ICONLEFT 


Forces the icon to the left, but leaves the tab label centered. By default, the control centers 
the icon and label, with the icon being to the left of the label. 


LABELLEFT 


Left-aligns both the icon and the label. 


MULTILINE 


Causes a tab control to display several rows of tabs, enabling all tabs to be displayed at 
the same time. 


GROUP 


Specifies the first control of a group of control in which the user can move from one 
control to the next with the arrow keys. 


HIDDEN 


The control is initially hidden. 


NOTAB 


The tab key cannot be used to move to this control. 
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NOBORDER 


No border is drawn around the control. 


Return value: 


The possible return values are: 


Success. 


less than 0 


Error with the in-memory dialog template or with the resource ID. 


Example: 


The following example creates a tab control with ID PAGES and multiline capability. Its data (the 
selected tab) is associated with attribute CURRENTPAGE. 


MyDialog^AddTabControl("PAGES","CURRENTPAGE", 10, 120, 200, 20, , 
"MULTILINE FIXED") 
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Static controls are used in applications as labels or to separate groups of controls. Although static 
controls are child windows, they cannot be selected. Because of that, they do not receive the keyboard 
focus and do not have a keyboard interface. A static control can have a notify style. With this style the 
control will receive mouse input and then notifies its parent dialog when the user clicks or double clicks 
the control. 


There are four basic types of static controls. Each type has one or more styles. 


Simple Graphics 
Text 

Image 
Owner-Drawn 


Simple graphic static controls draw a filled rectangle or a frame. Text static controls display text. Image 
static controls display an image, icon, bitmap or enhanced metafile. ooDialog does not have much, if any, 
support for owner-drawn static controls. 


The StaticControl class provides methods to query and modify static controls. By default, static controls 
are assigned a resource ID of -1. There is no way to query or modify static controls unless the control has 
a positive resource ID. Which in most circumstances is fine, usually static controls do not need to be 
modified. Be sure to assign a positive resource ID to static controls that will be modified during the 
execution of a dialog. 


Requires: 
The StaticControl class requires the class definition file oodWin32.cls: 


::requires "oodWin32.cls" 


Subclass of: 


The static control class is a subclass of the DialogControl Class and therefore inherits all methods of 


that class. 


Mixin Class Inherits: 


The static control class inherits from the following mixin classes, (indirectly through the 
DialogControl class.) 


The WindowBase 


The WindowExtensions 


Instantiation: 


Use the getStaticControl() method to retrieve an object of the static control class. To use this 
method, the static control must have a positive ID. 


Dynamic Definition: 


To dynamically define a static control in a UserDialog class, use one of the Add Static Control 
methods. 
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Event Notification 
To recieve notification of static control events use the connectStaticNotify)() method. 


Methods: 


The StaticControl class implements the class and instance methods listed in the following table: 


Table 13-1. StaticControl Instance Methods 


























Method... ..оп page 
new (Class method) new 
сейсоп getIcon 
getImage getImage 
getText getText 
setIcon setIcon 
setImage setImage 
setText setText 














13.1. new (Class method) 


The static control class is not intended to be instantiated directly by the programmer using the new() 
method. Rather the programmer should obtain a new static control object by using the getStaticControl() 
method of the .AdvancedControls class. 


13.2. setText 


»»--setText(--text--)---------------------------------------------------------- >< 


Sets the text of the static control. This only effects text static controls. For instance, text can not be set for 
frames or rectangles. 


Arguments: 


The single argument is: 


text 


The text the control should display. 
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Return value: 


This method returns a non-negative number. 


Success 
other 


Some error was detected. The number returned is the system error code. 


Example: 
This method is straight forward to use. 


static = self~getStaticControl (IDC_ST_FULLNAME) 
вас” ве Тех! ("James Madison") 


13.3. getText 


22==eb lets ta --- ---- >< 


Returns the current text of the control. This method has no effect on any type of static control other than 
the text static control. 


Details 
Sets the .SystemErrorCode variable. 


Arguments: 


This method does not have any arguments. 


Return value: 


Returns the text of the static control. If an error is detected, this method will set the 
.SystemEirrorCode variable and the empty string is returned. (It would be highly unusual for an error 
to occur.) 


Example: 


static = self~getStaticControl (IDC_ST_DESCRIPTION) 
text = static” getText 


13.4. seticon 


»»--setlIcon(--newImage--)------------------------------------------------------ >< 
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Sets or removes the icon image for this static control. This method only effects the image type static 


control. For instance an icon can not be set for a frame or rectangle. 


Details 
Raises syntax errors when incorrect arguments are detected. 


The programmer should manage the image objects as he thinks best. See the .Image documentation 
for a discussion of this. The static control does not make a copy of the icon, nor does it release an 


icon image. 


Arguments: 


The single argument is: 


newImage 
A .Image object that represents the image for the control, or .nil to remove an existing image. 


The image object must be an icon image. 


Return value: 


This method returns the existing image object, if there is one. Otherwise .nil is returned. 


Example: 


icon = .Image^getImage(.Image^toID(IDI QUESTION), .Image~toID(IMAGE_ICON) ) 


if \ icon^isNull then do 
oldIcon = iconControl^setIcon(icon) 


end 
else do 

-- handle error 
end 


13.5. getlcon 


>>--getIcon 


Gets the static control’s icon image, if there is one. Only the image type of static control can have an icon. 


Details 


Programmers should manage the image objects as they think best. See the .Image documentation for 
a discussion of this. The static control does not make a copy of the icon, nor does it release an icon. 


Arguments: 


This method takes no arguments. 
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Return value: 
The current icon .Image object for the control, if there is one. If the control does not have an icon 
set, then .nil is returned. 

Example: 


This example ... 


staticControl = self^getStaticControl(IDC, ST. ICON) 
icon = staticControl^getlIcon 


13.6. setimage 


»»--setImage(--imageÜ0bject--)----------------------------------- >< 


Sets or removes the image for the static control. An image сап only be set with the image type static 
control. 


Details 
Raises syntax errors when incorrect arguments are detected. 


Programmers should manage the image objects as they think best. See the .Image documentation 
for a discussion of this. The static control does not make a copy of the image, nor does it release an 
image. 

Arguments: 


The arguments are: 


imageObject 


A .Image object that represents the image for the control, or .nil to remove an existing image. 
The image object can be any image type, including an icon image. 


Return value: 
This method returns the existing image object, if there is one. Otherwise .nil is returned. 
Example: 
image = .Image~getImage("Camera.bmp", .Image^toID(IMAGE, BITMAP)) 
if \ image^isNull then do 
oldImage = staticControl^setlImage(image) 
if oldImage \== .nil then oldImage^release 
end 
else do 


-- handle error 


end 
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13.7. getlmage 


»»--getlmage(--4-------- 4--)--------------------------------------------------- >< 
+--type--+ 


Returns the static control’s image, if there is one. Only the image type static control will have an image. 


Details 
Raises syntax errors when incorrect arguments are detected. 


Programmers should manage the image objects as they think best. See the .Image documentation 
for a discussion of this. The static control does not make a copy of the image, nor does it release an 


image. 


Arguments: 


The only optional argument is: 


type 
Specifies the type of the image: bitmap, icon, cursor, or enhanced metafile. You can use 


.Image-toID() to get the correct numeric value for one of the following symbols: 
IMAGE BITMAP IMAGE ICON 
IMAGE CURSOR IMAGE ENHMETAFILE 


The default is IMAGE ВПМАР. 


The programmer does not have to use .Image-toID() to get the numeric value for type. The 
correct number itself can be used. In general, symbolic IDs are used to make code more 
readable and less prone to error. However, since the value of IMAGE CURSOR is 2, for 
example, the programmer could use 2 directly for the type argument. 


Return value: 
This method returns the .Image object for the control, if there is one. If no image has been set, then 
.hil is returned. 

Example: 
This example ... 


::method onExit 
expose staticPicture 


image = staticPicture^getImage(.Image^toID(IMAGE, CURSOR)) 
if \ image~isNull then image^release 
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In Windows the Button control has a number of different types or kinds. Most button types have a 
number of different styles. The style of a button effects its behavior and appearance. The appearance of a 
button is usually maintained by the operating system in combination with the programmer. 


"on 


In general people refer to "pushing," "clicking," or "checking" a button. The mouse is used to click a 
button and the enter key to push a button. Checking a button can be done with the mouse or the keyboard. 
Buttons have a state, the most common of which are checked, unchecked, pushed, and focused. 


The five kinds of buttons are: 


* Push Buttons 
* Check Boxes 
• Radio Buttons 
* Group Boxes 


* Owner Drawn Buttons 


ooDialog provides these classes to allow the programmer to interface with the underlying button 
controls: 


Table 14-1. ooDialog Button Control Classes 


























Button Control Type ooDialog Class 

Push Button ButtonControl Class 

Check Box Button CheckBox Class 

Raido Button RadioButton Class 

Group Box GroupBox Class 

Owner Drawn Button AnimatedButton Class, ButtonControl Class 








14.1. ButtonControl Class 


Push buttons are rectangular controls containing a label (a text string.) an icon, or a bitmap defined by the 
programmer. The label or image indicates what the button does when it is pushed or clicked. A push 
button is either standard or default. 


Standard push buttons usually start an operation. The button will receive the keyboard focus when the 
user clicks it. On the other hand, the default push button will indicate the default choice, which would 
normally be the most common choice. The default button does not have to have the input focus to be 
selected. It is selected by the user pressing the ENTER key when the dialog box has the focus, no matter 
which control currently has the input focus. 


The ButtonControl class provides methods to query and modify push button controls. In addition, the 
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class has methods that allow the Rexx programmer to partially implement owner drawn buttons using 
bitmaps. 


Requires: 
The ButtonControl class requires the class definition file oodwin32.cls: 


::requires "oodwin32.cls" 


Subclass of: 
The button control class is a subclass of the DialogControl class and therefore inherits all methods 
of that class. 

Mixin Class Inherits: 


The button control class inherits from the following mixin classes, (indirectly through the 
DialogControl class.) 


The WindowBase 


The WindowExtensions 


Instantiation: 


Use the getButtonControl() method to retrieve an object of the button control class. 


Dynamic Definition: 


To dynamically define a button control in a UserDialog class, use one of the add button methods 
described in the Add Button Control section. That section also describes methods for adding radio 
buttons, check boxes, etc.. Only the addButton... methods are used to add a ButtonControl object. 


Event Notification 


The programmer can use these methods to recieve notifications of button control events: the 
connectButton() method, or the connectButtonNotify() method. 


Methods: 


The ButtonControl class implements the class and instance methods listed in the following table. 


Table 14-2. ButtonControl Instance Methods 






































Method... ..оп page 
changeBitmap changeBitmap 

click click 

dimBitmap dimBitmap 
displaceBitmap displaceBitmap 
drawBitmap drawBitmap 
getBitmapSizeX getBitmapSizeX 
getBitmapSizeY getBitmapSizeY 
getBmpDisplacement getBmpDisplacement 
getIdealSize getIdealSize 
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Method... ..оп page 
getImage getImage 
getImageList getImageList 
getTextMargin getTextMargin 
push push 
scroll scroll 
scrollBitmapFromTo scrollBitmapFromTo 
scrollText scrollText 
setImage setImage 
setImageList setImageList 
setTextMargin setTextMargin 
state state 
state= state= 
style= style= 
14.1.1. push 
>>--push--------------------------------------- >< 


The push method simulates the user pushing the associated button control. It allows a Rexx programmer 
to produce the exact same behavior from within an ooDialog program as the behavior produced by the 
user pushing the button in the dialog. 


Arguments: 


There are no arguments to this method. 


Return value: 


This method does not return a value. 


Example: 


This example comes from an imaginary program that has a list of window handles. The dialog has a 
Refresh button that the user can push to update the window list. The code comes from a section of 
the program that is checking if a specific window handle is valid. If the handle is not valid, the code 
simulates the user pushing the Refresh button to update the window list. 


::method validateHandle private 
use strict arg hwnd 
if \ self~isWindowHandle(hwnd) then do 
self~getButtonControl (IDC_PB_REFRESH) ~push 
return .false 
end 


return .true 
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14.1.2. click 
эж e скат os Se a >< 


The click method programmatically clicks the associated button control. It simulates the user clicking the 
button and produces exactly the same behavior as if the user had clicked on the button with the mouse. 


Arguments: 


This method takes no arguments. 


Return value: 


This method does not return any value. 


Example: 


This example closes the dialog as if the user had clicked the cancel button. (Provided of course that 
the dialog has a cancel button.) 


self^getButtonControl(IDCANCEL)^click 


14.1.3. state 
>>--враре------+т лента я ЯТ >< 


The state method retrieves Ше current state of Ше associated button control. 


Return value: 


A text string that can contain one or more of the following keywords, separated by blanks: 


"CHECKED" 


The radio button or the check box is checked. A radio button is checked when it contains a 
black dot, a check box is checked when it contains a check mark. 


"UNCHECKED" 


The radio button or the check box is not checked. A radio button is not checked when it does 
not contain a black dot and a check box is not checked when it does not contain a check mark. 


"INDETERMINATE" 


A 3-state check box button is neither checked nor unchecked. Only 3-state check box buttons 
can be in this state. When in the indeterminate state, the check box button is drawn in a 
visually distinctive manner that is different from checked or unchecked. Exactly how the 
indeterminate state is drawn is dependent on the operating system version. 


"PUSHED" 


When a button is in the pushed state it is drawn as a sunken button, otherwise it is drawn as a 
raised button. The user causes a button to be in the pushed state by clicking the button with the 
left mouse button. As long as the mouse button is held down, the button will be drawn as 
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pushed. When the user releases the mouse button, the button will resume its not pushed state. 
When this keyword is not in the text string, the button is not in the pushed state. 


"FOCUS" 


The button has the keyboard focus. When this keyword is missing from the text string, the 
button does not have the focus. 


Example: 


button = MyDialog^GetButtonControl("IDOK") 
if button == .Nil then return 
say button^State 


The result could be "UNCHECKED FOCUS". 


14.1.4. state= 


2»--state---newState----------------------------- >< 


The state= method sets the state for the associated button control. 


Arguments: 


The only argument is: 


newState 


A text string that contains one or more of the following keywords, separated by a blank: 


CHECKED UNCHECKED 
PUSHED NOTPUSHED 
INDETERMINATE FOCUS 


CHECKED 


The radio button or the check box is to be set to the "checked" state. 


UNCHECKED 


The radio button or the check box is to be set to the "unchecked" state. 


PUSHED 


The button is to be set to the "pushed" state. 


NOTPUSHED 


The "pushed" state is to be removed from the button. 


INDETERMINATE 


The 3-state check box button is to be set to the "indeterminate" state. This state can only 
be applied to 3-state check box buttons. 
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FOCUS 


The button is to be set to the "focused" state. 
Example: 


button = MyDialog^GetButtonControl("IDOK") 
if button == .Nil then return 
button” state="FOCUS PUSHED" 


Notes: 
Some points to remember when using this method. 


1. The checked, unchecked or indeterminate states have no meaning for a push button. Setting a 
push button to one of these states therefore has no effect. 


2. A radio button or check box can be set to only one of the checked, unchecked or indeterminate 
states. If more than one of these states is specified in the text string the button is set to the state 
that is first in the string. 


3. Only 3-state check box buttons can be set to the indeterminate state. If this keyword is used for 
a button that is not a 3-state button then the button’s state is not changed. 


4. To change a button state to not focused programmatically use one of the ooDialog methods that 
move the focus: TabToNext, TabToPrevious, SetFocus, ЕосизПепа, etc.. 


14.1.5. style= 


2»--sityle---newOtyle----------------------------- >< 


The style= method changes the style of the associated button control. 


Note: In the past, the documentation for this method was incomplete or misleading. There are really 
two aspects to a button, its type (or kind) and its style. Many of the button styles only have meaning 
within the same type of button. These styles can not be applied to a button of a different type after 
the button has been created. 


For instance, the AUTOCHECKBOX style can only be applied to a check box type of button. Trying to 
give this style to a radio type button has no effect. Because of this, certain of the style key words 
have no effect. They are listed here only because they were listed in previous versions of the 
documentation. This may have lead someone to use the key word in their code. An example is the 
GROUPBOX key word. The group box type of button only has one style. This style can not be 
applied to any other type of button, so setting the style of any button to GROUPBOX has no effect, 
and has never had any effect. 


However, within each type of button, the styles that apply to that type of button can be changed. For 
instance, a check box type of button that has the 3STATE style, can be changed to have the 
AUTOCHECKBOX style or to have the AUTOSSTATE style. 
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Arguments: 


The only argument is: 


newStyle 


A text string containing one or more of the following keywords separated by blanks. Common 
sense should be used when constructing the newStyle string. If mutually exclusive key words 
are used, the outcome will be dependent on the order of the key words. 


DEFPUSHBUTTON TEXT NOTPUSHLIKE 
LEFTTEXT MULTILINE AUTO3STATE 
BOTTOM CHECKBOX RIGHT 
PUSHBOX ICON NOTMULTILINE 
RIGHTBUTTON NOTIFY GROUPBOX 
VCENTER AUTOCHECKBOX  HCENTER 
RADIO BITMAP NOTNOTIFY 
NOTLEFTTEXT FLAT OWNERDRAW 
PUSHLIKE 3STATE TOP 
AUTORADIO LEFT NOTFLAT 
DEFPUSHBUTTON 


In a dialog, the default push button is the button that is pushed when the Enter key is 
pressed. Changing the default push button will change the behavior of the dialog when the 
user presses the enter key. 


PUSHBOX 


A push button that does not display the button face or border, only the text appears. This 
button style is not applicable when Windows themes are in use. 


RADIO 
A radio button the state of which has to be maintained by the programmer. 
AUTO 


A radio button where the operating system maintains the check state for all radio buttons 
in the same group. When one radio button in the group is checked by the user, the 
operating system unchecks all other buttons in the group. 


CHECKBOX 


A check box where the state has to be maintained by the programmer. The state can only 
be checked or unchecked. 


AUTOCHECKBOX 
A check box where the operating system maintains the check state for the programmer. 
3STATE 


A check box button that has a grayed state as well as checked or unchecked. The greyed 
state shows that the check state of the button is not determined. The programmer needs to 
manage the state of the button when it is clicked. 
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AUTO3STATE 


A check box button that is the same as a three-state check box except that the operating 
system maintains the check state for the programmer. 


GROUPBOX 


This key word has no effect. 


OWNERDRAW 


This key word has no effect. 


LEFTTEXT 


Places the text on the left of the button for a radio button or check box. This style and 
RIGHTBUTTON are equivalent. 


RIGHTBUTTON 


Places the button on the right of the text for a radio button or a check box. This style is the 
same as LEFTTEXT. 


NOTLEFTTEXT 
Removes the LEFTTEXT style. 


TEXT 


The button displays text. 


ICON 


The button displays an icon image. 


BITMAP 


The button displays a bitmap image. 


LEFT 


The button has its text left-justified in the button rectangle. 


RIGHT 


The button has its text right-justified in the button rectangle. 


HCENTER 


The button has its text centered horizontally in the button rectangle. 


TOP 


The text is placed at the top of the button rectangle. 


BOTTOM 


The text is placed at the bottom of the button rectangle. 
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VCENTER 


The text is vertically centered in the button rectanble. 


PUSHLIKE 


Causes a radio button or check box button to behave like a push button. 


MULTILINE 


Causes the text for a button to wrap to multiple lines if the text is too long for the width of 
the button. 


NOTIFY 


Enables a button to send the kill focus and set focus messages. See the 
connectButtonNotify method of the MessageExtensions Class. If the button does not have 
this style, kill and set focus events will not be received, if the programmer does 
connectButtonNotify() to connect those events. 


FLAT 


Gives the button a flat appearance. This style is not applicable when Windows themes are 
in effect. 


NOTPUSHLIKE 


Removes the push like style. 


NOTMULTILINE 


Removes the multi-line style. 


NOTNOTIFY 


Removes the notify style. 


NOTFLAT 


Removes the flat style. 


Example 1: 
The following example makes the OK button the default button: 


button = MyDialog^GetButtonControl("IDOK") 
if button == .Nil then return 
button^style-"DEFPUSHBUTTON" 


Example 2: 


This example changes the text of a check box button depending on the state another check box. 
When the button text is long, the multi-line style is added and the placement of the text in relation to 
the button rectangle is changed. When the text is short, the button style is set back to the default 
style. 
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::method idCheckOne 
use arg wParam, 1Param 


id = .DlgUtil~loWord (wParam) 

if self^getCheckControl(id)^checked then do 
chkButton = self^getCheckControl(IDC CHECK TWO) 
chkButton^style = "MULTILINE TOP HCENTER" 
chkButton^setTitle("Use IPv6 not IPv4 during this connection") 

end 

else do 
chkButton = self^getCheckControl(IDC CHECK TWO) 
chkButton^style = "NOTMULTILINE VCENTER LEFT" 
chkButton^setTitle("Connect") 

end 


14.1.6. getldealSize 


>2==реЕтаваі51л6е=============-=====9=н===5======= >< 


This method queries the button control for its ideal size. The ideal size is the size that best fits its text or 
image. (If the button has an image.) 


Details 
This method requires Common Control Library version 6.0 or later. If necessary use the 
comCtl32Version() method to determine the current version of the library. 

Arguments: 


This method has no arguments. 


Return value: 


The possible return values are: 


A .Size object 


The ideal size for the button. 


The .nil object 


Some unanticipated error. This is very unlikely to happen. 


Example: 


size = self~getButtonControl (IDC_PB_REVIEW) ~getIdealSize 
say ’The ideal height for the button is’ size^height' 
say ’The ideal width for the button is’ size^width 


/* Üutput might be for example: 

* The ideal height for the button is 24 
* The ideal width for the button is 45 
*/ 
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14.1.7. getTextMargin 


>2--пе Тех Матра----------------------+--+-<+-<<-<+<+ + >< 


This method retrieves Ше margins used to draw text within Ше assoicated button control. 


Details 
This method requires Common Control Library version 6.0 or later. If necessary use the 
comCtl32Version() method to determine the current version of the library. 

Arguments: 


This method does not take any arguments. 


Return value: 


The possible return values are: 


A .Rect object 


The margin for drawing text in the button. 


The .nil object. 


An unanticipated error. This is not likely to happen. 


Example: 


This example gets the text margins for the Redraw button and displays the information: 


margins = self~getButtonControl (IDC_PB_REDRAW) ~getTextMagin 
say ’The text margins for the "Redraw" button:’ 

say ’ Left: ^" margins" left 

say ’ Тор: > margins” top 

say ’ Right: " margins”right 

say ’ Bottom:’ margins bottom 


/* Output might be for example: 
* The text margins for the "Redraw" button: 


* Left: 1 
* Top: 1 
* Right: 1 
* Bottom: 1 
*/ 


14.1.8. setTextMargin 


»»--setTextMargin(--margins--)------------------- >< 


This method sets the margins for drawing text in the associated button control. 
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Details 


This method requires Common Control Library version 6.0 or later. If necessary use the 
comCtl32Version() method to determine the current version of the library. 


Raises syntax errors when incorrect arguments are detected. 
Arguments: 


The only argument is: 


margins 


A .Rect object describing the new margins. 


Return value: 


The possible return values are: 


. true 


Success 


.false 


Failed. 


Example: 
This example sets a new text margin of 5 for the button control. 


margins - .Rect^new(5, 5, 5, 5) 
self^getButtonControl(IDC. PB. SHOW DETAILS)^setTextMargin(margins) 


14.1.9. getimageList 


2»--petlmageList---—---------95-----06ceame cem >< 
This method retrieves information describing the image list for the associated button, if there is one. 


Details 


This method requires Common Control Library version 6.0 or later. If necessary use the 
comCtl32Version() method to determine the current version of the library. 


Arguments: 


The are no arguments to this method. 
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Return value: 


The return value is: 


A .Directory object. 


The image list information is returned in a Directory object. See the setImageList() method for 
clarification of the information returned. The directory object has the following entries: 


imageList 


The .ImageList object containing the images for the button. 


rect 


A .Rect object that specifies the margin around the image. 


alignment 


The numeric flag that specifies the alignment of the image list. 


The .nil object 


The Nil object is returned if the button does not have an image list, or for some other 
unanticipated error. 


Example: 
This example gets the image list from the View push button and displays the information returned. 
pbView = self~getButtonControl (IDC_PB_VIEW) 
d = pbView^getImageList 


say ’Got image list:' d 
if d <> .nil then do 


say ? image: ^" d'imageList 
say ? rect: > d^rect 
say ! align: ? self~getAlignmentText (d~alignment) 


say ?'Image margins:’ d'rect left'," d'rect^top'," d^rect^right'," d^rect^ bottom 
end 


::method getAlignmentText private 

use strict arg align 

select 
when align - .Image^toID(BUTTON. IMAGELIST, ALIGN, CENTER) then return "center" 
when align - .Image^toID(BUTTON, IMAGELIST. ALIGN LEFT) then return "left" 
when align - .Image^toID(BUTTON, IMAGELIST, ALIGN, RIGHT) then return "right" 
when align - .Image^toID(BUTTON, IMAGELIST, ALIGN, TOP) then return "top" 
when align - .Image^toID(BUTTON, IMAGELIST, ALIGN, BOTTOM) then return "bottom" 
otherwise return "error" 

end 

-- End select 
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/* Output might be for example: 


Got image list: a Directory 
image: an ImageList 
rect: a Rect 
align: left 

Image margins: 1, 1, 1, 1 


*/ 


14.1.10. setlmageList 


»»--setImagelist(--imageList--,--4-------- *--,--4------- E ------------------- >< 
+-margin-+ +-align-+ 


Sets, or removes the image list for the button. To remove an existing image list, the programmer passes in 
.nil for the first argument. 


Using an image list with a button is a new feature that requires Windows XP or later. It provides an 
easier, more convenient way to do owner-drawn buttons. This method should be the preferred way for the 
ooDialog programmer to do bitmap buttons, where the primary purpose is to provide an image on the 
button. Using an image list will automatically give the button the same look and feel as other buttons on 
the system. 


A .ImageList object is used to supply the images for the button. If the image list only contains 1 image at 
the first index, then that image is used for all button states. If more than 1 image is supplied, the the 
image at each index is used for the button state with this mapping: 


index 0 2 Normal 
index | = Hot 
index 2 = Press 
index 3 = Disabled 
index 4 = Defaulted 
index 5 = StylusHot 


StylusHot is only used on tablet computers. If more than 1 image is supplied, but some indexes do not 
have an image, then the system does not draw an image for that state. The programmer retains ownership 
of the image list. What this means in essence is the programmer decide when, or if, the image list should 
be released. See the discussion in the .ImageList class about releasing image lists if needed. If you 
release the image list while the dialog is stil active, the images on the button disappear. 


A sample program: imageButton.rex in the samples directory is provided that shows how to use this 
method. It is in: samples\oodialog\examples. 


Details 


This method requires Common Control Library version 6.0 or later. If necessary use the 
comCtl32Version() method to determine the current version of the library. 


Sets the .SystemErrorCode variable. 


Raises syntax errors when incorrect arguments are detected. 
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Arguments: 


The arguments are: 


imageList 
A .ImageList object containing the images for the button. If this argument is the Nil object, 
then any existing image list is removed. 

margin 


Optional. A .Rect object containing the margins around the image. The default is a 0 margin. 


alignment 


Optional, Specifies the alignment of the image on the button. You can use .[mage~toID() to get 


the correct numeric value for one of the following symbols, 
BUTTON_IMAGELIST_ALIGN_LEFT BUTTON_IMAGELIST_ALIGN_RIGHT 
BUTTON_IMAGELIST_ALIGN_TOP BUTTON_IMAGELIST_ALIGN_BOTTOM 
BUTTON_IMAGELIST_ALIGN_CENTER 


or use the numeric value itself. 


The default is BUTTON_IMAGELIST_ALIGN_CENTER. 


Return value: 


The possible return values are: 


oldImageList 


If there is an existing image list, it is returned in the same format specified in the () method. 


.nil 


The Nil object is returned if there was no existing image list, and also if an error is encountered. 
In general, the .SystemErrorCode variable should be set to non-zero if an error happend. 


Example: 


This example creates an image list from a set of bitmap files. Each image represents one of the 
possible buttons states. In the program, as the button changes states, the text on the button is also 
changed. So, the program calculates the ideal button size using the longest label, then resets the 
button size to the ideal size. 


Since the image list API is only available with XP or later, the program checks that the API is 
available before proceeding. For further information on some of the methods used in the example 
see getIdealSize and comCtl32 Version. 


if .DlgUtil^comCtl32Version < 6 then return -2 


files = .array~new() 

files[1] = "resources\Normal.bmp" -- Normal 
files[2] = "resources\Hot.bmp" -- Hot (hover) 
files[3] = "resources\Pushed. bmp" -- Pushed 
files[4] = "resources\Disabled.bmp" -- Disabled 
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files[5] = "resources\Default. bmp" -- Default button 
files[6] "resources\Hot. bmp" -- Stylus hot, tablet PC only 


-- Set the flags to create a 24 bit color, masked image list. 
flags = .DlgUtil~or(.Image~toID(ILC_COLOR24), .Image~toID(ILC_MASK) ) 
imageList = .ImageList^create(.Size^new(61, 46), flags, 10, 10) 


images = .Image^fromFiles(files) 
cRef = .Image~colorRef(255, 255, 255) 
imageList^addImages(images, cRef) 


align = .Image^toID(BUTTON IMAGELIST, ALIGN LEFT) 
margin = .Rect^new(1) 


ret = pbView^setImageList(imagelist, margin, align) 
if .SystemErrorCode <> 0 then do 

-- put some error handling here 

return -1 
end 


-- Temporarily set the title to the longest text, to calculate 
-- the ideal size. 

pbView^setTitle("DEATH if you touch me") 

bestSize = pbView^getlIdealSize 


-- Not reset the button label and set the size to the ideal size. 
pbView^setTitle("View Pictures") 
pbView~setRect(0, 0, bestSize^width, bestSize^height, "NOMOVE") 


return 0 


14.1.11. getlmage 


>2--реншаре-----------------------------+-+- >< 


Retrieves a button’s image if one is set, or .nil if Ше button does not have an image associated with it. 


Arguments: 


This method does not take any arguments. 


Return value: 


This method returns the .Image object for the button, or .nil if the button does not have an image . 


Example: 


In this example a bitmap has been set for the button on a popup dialog. When the dialog closes, 
bitmap image is retrieved from the button and released. 


::method cancel 
button = self^getButtonControl(IDC РВ PUSHME) 
image = button” getImage 
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if image <> .nil then image^release 
return self^cancel:super 


14.1.12. setlmage 


»»--setImage(-newImage-)---------------------------------------- >< 


Sets, or removes, the image assoicated with a button. The image can bet a bitmap, icon, or cursor. Note 
that the button style has to match the type of image. For cursors and icons, the button must be an ICON 
button. For bitmap images, the button must be a BITMAP button. 


To completely remove an image assoicated with the button use .nil for the argument. 


Details 


Raises syntax errors when incorrect arguments are detected. 


Arguments: 
The single required argument is either Ше „пасе object to be associated with the button or .nil. The 
use of .nil for the argument removes any existing image. 

Return value: 


This method returns the old image, if there was one, otherwise .nil. 


Example: 


This example gets an image from the resource file for a ResDialog and assoicates it with the Push 
Me button. 
::method initDialog 
module = .Resourcelmage^new("imageButton.dll", self) 
image = module^getImage(101) 
self~getButtonControl (IDC_PB_PUSHME) ~setImage (image) 
self~connectButton(IDC_PB_PUSHME, onPushMe) 


14.1.13. ChangeBitmap 


>>-aButtonControl~ChangeBitmap (--bmpNormal-- ,--+------------ quc 


+-bmpSelected-+ +-bmpDisabled-+ +-,--+-ЕВАМЕ----+-+ 
+-USEPAL---+ 
+-INMEMORY-+ 
+-STRETCH--+ 


The ChangeBitmap method changes the bitmap of a bitmap button. 
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Arguments: 


The arguments are: 


bmpNormal 


The (alphanumeric) name, (numeric) resource ID, or handle of a bitmap that is displayed when 
the button is neither selected, nor focused, nor disabled. If you specify the bitmap handle, the 
INMEMORY option must be specified. 


This option is used if none of the other arguments is specified. 


bmpFocused 
The (alphanumeric) name, (numeric) resource ID, or handle of a bitmap that is displayed when 
the button is focused. The focused button is activated when the Enter key is pressed. If you 
specify the bitmap handle, the INMEMORY option must be specified. 

bmpSelected 
The (alphanumeric) name, (numeric) resource ID, or handle of a bitmap that is displayed when 
the button is clicked and held. If you specify the bitmap handle, the INMEMORY option must 
be specified. 

bmpDisabled 


The (alphanumeric) name, (numeric) resource ID, or handle of a bitmap that is displayed when 
the button is disabled. If you specify the bitmap handle, the INMEMORY option must be 
specified. 

styleOptions 


The last argument can be one of the following: 


FRAME 
Draws a frame around the button. When you use this option, the bitmap button behaves 
like a normal Windows button except that a bitmap is shown instead of text. 

USEPAL 


Takes the colors of the bitmap file and stores them as the system color palette. This option 
is needed when the bitmap was created with a palette other than the default Windows 
color palette. Use it for one button only because only one color palette can be active at a 
time. 


This option is not valid for a bitmap loaded from a dynamic-link library. 


INMEMORY 


This option must be used if the named bitmaps are already loaded into memory by using 
the LoadBitmap method (see LoadBitmap). In this case, you must specify a bitmap 
handle instead of a file name or ID. 
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STRETCH 


If this option is specified and the extent of the bitmap is smaller than the extent of the 
button rectangle, the bitmap is adapted to match the extent of the button. This option has 
no effect on bitmaps loaded from a dynamic-link library. 


Example: 


button = MyDialog^GetButtonControl("IDOK") 

if button == .Nil then return 

button^ChangeBitmap("AddBut n.bmp", "AddBut_f.bmp", "AddBut s.bmp", , 
"AddBut d.bmp", "FRAME") 


See also ConnectBitmapButton. 


14.1.14. DisplaceBitmap 


»»-aButtonControl^DisplaceBitmap(--x--,--y--)------------------ >< 


The DisplaceBitmap method sets the position of a bitmap within a bitmap button. 


Arguments: 


The arguments are: 


x 
The horizontal displacement, in screen pixels. A negative value can also be used. 
y 
The vertical displacement, in screen pixels. A negative value can also be used. 
Example: 


The following example moves the bitmap within the associated bitmap button 4 screen pixels to the 
right and 3 pixels upward: 


button = MyDialog^GetButtonControl("IDOK") 

if button == .Nil then return 

parse value button GetBmpDisplacement with dx ду 
button^DisplacementBitmap(244, dx+4, dy-3) 


14.1.15. GetBmpDisplacement 


»»-aButtonControl^GetBmpDisplacement--------------------------- >< 


The GetBmpDisplacement method retrieves the position of a bitmap within a bitmap button. 
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ntrols 


Return value: 


The horizontal and vertical positions of the bitmap, in screen pixels and separated by a blank. 


Example: 


See DisplaceBitmap. 


14.1.16. Scroll 


»»-aButtonControl^Scroll(--xPos--,--yPos--,--left--,--top--,--right--,--bottom--)-»« 


The Scroll method moves the rectangle within the associated button and redraws the uncovered area with 
the button background color. It is used to move bitmaps within bitmap buttons. 


Arguments: 


The arguments are: 


xPos, 


The new position of the rectangle, in screen pixels. 


yPos 


left, top, right, bottom 


The upper left and lower right corner of the rectangle to be moved. 


14.1.17. ScrollText 


>>-aButtonControl~ScrollText (--text-- ,--+---------- hes mu в яняя- > 


>--+-------------------------- +--,--+----------- +--,-- 

| ф=-=-с=зезеззшешә + | +-displaceY-+ 
| V | | 
4-"---—4-THIN-------4-4--"-4 

+-EXTRALIGHT-+ 

+-LIGHT------ + 

*-MEDIUM----- + 

+-SEMIBOLD---+ 

+-EXTRABOLD--+ 

*-BÜLD------- + 

+-HEAVY------ + 

+-UNDERLINE--+ 

+-ITALIC----- + 

+-STRIKEOUT--+ 

+-0----- + 
532 


+-fontSize-+ 


+-4----+ +-10----+ 
+------ +--,--+------- +--> 
+-step-+ +-sleep-+ 
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The ScrollText method scrolls text in the associated button with the given font, size, and color. The text is 
scrolled from right to left. If the method is started concurrently, call it a second time to stop scrolling. 
The associated button must have the OWNERDRAWN style. 


Arguments: 


The arguments are: 


text 


A text string that is displayed and scrolled. 


fontName 


The name of the font used to write the text. If omitted, the system font is used. 


fontSize 


The size of the font used to write the text. If omitted, the standard size (10) is used. 


fontStyle 
This argument can be one or more of the keywords listed in the syntax diagram. If you use 
more than one keyword, put them in one string, separated by blanks. 

displaceY 
The vertical displacement of the text relative to the top of the client area of the window. The 
default is 0. 

step 


The amount of screen pixels that the text is moved in each cycle. The default is 4. 


sleep 


The time, in milliseconds, that the program waits after each movement to determine the 
scrolling speed. The default is 10. 


color 


The color index used for the text. The default is 0, which is black. 


Example: 


The following example scrolls the string "Hello world!" from left to right within the associated 
button. The text is located 2 pixels below the top of the client area, one move is 3 screen pixels, and 
the delay time after each movement is 15 ms. 


button = MyDialog^GetButtonControl("IFOK") 
if button == .Nil then return 
button~ScrollText ("Hello world!", "Arial", 36, "BOLD ITALIC", 2, 3, 15, 4) 
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14.1.18. GetBitmapSizeX 


»»-aButtonControl^GetBitmapSizeX------------------------------- >< 


The GetBitmapSizeX method retrieves the width of the bitmap that is set for the associated button. 


Return value: 


The width of the bitmap, in screen pixels. 


14.1.19. GetBitmapSizeY 


»»-aButtonControl^GetBitmapSizeY------------------------------- >< 


The GetBitmapSizeY method retrieves the height of the bitmap that is set for the associated button. 


Return value: 


The height of the bitmap, in screen pixels. 


14.1.20. DrawBitmap 


+-0----+ +-0----+ +-0----+ 
»»-aButtonControl^DrawBitmap(--4------4--,--4------4--,--4------4--,--» 
+-tarx-+ +-тагу-+ +-вгсх-+ 
+-0----+ +-0----- + +-0------ + 
>--+------ 4--,--4------- 4--,--4-------- +--)-------------------- >< 
+-вгсу-+ +-width-+ +-height-+ 


The DrawBitmap method draws the bitmap of the associated bitmap button. You can also use this 
method to move a bitmap or part of it. 


Contrary to the method DisplaceBitmap, which sets a permanent position for the bitmap, DrawBitmap 
immediately draws the bitmap, or part of it, at the specified position. If the button must be refreshed, the 
bitmap is drawn at the position set with DisplaceBitmap. DrawBitmap is used by ScrollBitmapFromTo, 
for example. 


Arguments: 


The arguments are: 


tarx,tary 


The position relative to the client area of the button where the bitmap is to be displayed. The 
default is 0,0. 
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SICX,STCYy 


The offsets that specify the first pixel in the bitmap to be displayed. If you omit these 
arguments, the pixel at position 0,0 is the first pixel displayed. 


width,height 


The width and height of the bitmap. If you omit these arguments or specify 0, the entire bitmap 
is displayed at the specified position. You can use these arguments to display only parts of the 
bitmap. 


Return value: 


О if the bitmap could be drawn. 


Note: You can use the DrawBitmap method to animate a bitmap by providing a bitmap that contains 
several images and use the offset and extension arguments to display a single image of the bitmap. 


14.1.21. DimBitmap 


»»-aButtonControl^DimBitmap(--bmpHandle--,--width--,--height--,--» 
+-2----- + +-2----- + +-10----+ 

>--+------- 4--,--4------- T--,--4------- +--)-------------------- >< 
+-вЪерх-+ +-stepy-+ +-steps-+ 


The DimBitmap method draws a bitmap step by step. 


Arguments: 


The arguments are: 


bmpHandle 
A handle to the bitmap loaded with LoadBitmap. 


width, height 


The extensions of the bitmap. 


stepx, stepy 


The number of incremental pixels displayed at each step. The default is 2,2. 


steps 


The number of iterations used to display the bitmap. The default is 10. 
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Return value: 


This method does not return a value. 


14.1.22. ScrollBitmapFromTo 


»»-aButtonControl^ScrollBitmapFromTo(--fromX--,--fromY--,--toX--,--toY--,--» 


»--stepx--,--stepy--,--delay--,--displace--)------------------- >< 


The ScrollBitmapFromTo method scrolls the bitmap within the associated bitmap button from one 
position to another. 


For an explanation of the arguments, refer to ScrollBitmapFromTo. 


14.2. RadioButton Class 


Radio buttons consist of a round button and a programmer defined label, icon, or bitmap that indicates to 
the user a choice. Radio buttons are typically grouped together as a set of mutually exclusive options. 
Radio buttons can be either standard or automatic. The system manages the check state of automatic 
radio buttons. The state of a radio button can be either checked or cleared (unchecked.) 


The RadioButton class provides methods to query and modify radio button controls. 


Requires: 
The RadioButton class requires the class definition file oodWin32.cls : 


::requires "oodWin32.cls" 


Subclass of: 
The radio button class is a direct subclass of the ButtonControl class, and therefore an indirect 
subclass of the DialogControl class class. Thus it inherits all the methods of both classes. 
Mixin Class Inherits: 


The radio button class inherits from the following mixin classes, (indirectly through the 
DialogControl class.) 


The WindowBase 


The WindowExtensions 


Instantiation: 


Use the getRadioControl() method to retrieve an object of the radio button class. 
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Dynamic Definition: 


To dynamically define a radio button in a UserDialog class, use one of the add button methods 
described in the Add Button Control section. That section also describes methods for adding push 
buttons, check boxes, etc.. All the methods to add radio buttons begin with: addRadio. 


Event Notification 


A radio button, is a button, and the programmer uses the same methods to recieve notifications of of 
events as with a ButtonControl: the connectButton() method, or the connectButtonNotify() method. 


Methods: 


The RadioControl class implements the class and instance methods listed in the following table: 


Table 14-3. RadioButton Class and Instance Methods 
































Method... ...Description 
checkInGroup (Class) checkInGroup 
check check 

checked checked 
getCheckState getCheckS tate 
indeterminate Deprecated indeterminate 
isChecked Deprecated isChecked 
uncheck uncheck 





14.2.1. checkInGroup (Class) 
»»--checkInGroup(--dlg--,--idFirst--,--idLast--,--,--idCheck--)---------------- >< 


Adds a check mark to (checks) the specified radio button in a group and removes a check mark from 
(clears) all other radio buttons in the group. 


Details 
Raises syntax errors when incorrect arguments are detected. 
Arguments: 
The arguments are: 
dig 
The dialog that contains the radio button to be checked. 


idFirst 


The resource ID of the first radio button in the group. 
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idLast 


The resource ID of the last radio button in the group. 


idCheck 


The resource ID of the radio button that is to be checked. 


Return value: 


This method return 0 on success and a system error code if a problem is detected. 


Example: 
This method is simple to use: 


ret - .RadioButton^checkInGroup(self, IDC RB. WHITE, IDC RB BLACK, ТОС GREEN) 
return 0 


14.2.2. checked 
>2--снескед---------------+-+--++--- --- >< 


Determines if the button is checked, or not. 


Arguments: 


There are no arguments. 


Return value: 


Returns true if the button is checked, otherwise false. 


Example: 
This example determines if the user is choosing to print the current page, all pages, or a selection: 


if Self^getRadioControl(IDC, RB, CURRENT) ^ checked then do 
--Print the current page ... 

end 

else if self^getRadioControl(IDC, RB ALL)^checked then do 
-- Print all pages 


end 
else do 

-- Must be print the selection ... 
end 


14.2.3. getCheckState 


>>--рефСресковаве-------- 9959559 ---- ен SSS Rea SS, >< 


Returns a keyword indicating Ше check state of Ше radio button, checked or unchecked. 
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Arguments: 


There are no arguments to this method. 


Return value: 


The return value is a keyword indicating the checked state of the radio button and will be exactly 
one of the following: 


UNCHECKED The radio button is not checked. 


CHECKED The radio button is checked. 
UNKNOWN The object is not a radio button. 
Example: 


This method is straightforward to use: 


rb = self~getRadioControl (IDC_RB_ITALIC) 
if rb^getCheckState == "CHECKED" then self^printInItalics() 


14.2.4. check 


>>--спеск------------ -<------- --- >< 


The check method puts Ше button in Ше checked state. The system will redraw Ше button with the check 
mark appropriate for the button. 


14.2.5. uncheck 


>>--исеск---------- SSeS SS ass SSS >< 


The uncheck method puts the button in the unchecked state. The system will redraw the button without 
the check mark. 


14.2.6. isChecked (deprecated) 


Note: This method is deprecated. It is replaced by the functionally equivalent getCheckState() 
method for radio buttons, and the overridden getCheckState() method for check boxes. This method 
was poorly named and in some circumstances produced inconsistent results. Do not use this method 
in new code. Try to migrate existing code to the appropriate getCheckState() method. This method 
may not exist in future versions of ooDialog. 
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14.2.7. indeterminate (deprecated) 


Note: This method is deprecated. It is replaced by the functionally equivalent setIndeterminate() 
method of the CheckBox class. Radio buttons can not be set to indeterminate. Using this method 
with a radio button sets it to the checked state, not the indeterminate state. In addition, this method 
was poorly named. One can check a button, but one does not indeterminate a check box. Do not use 
this method in new code. Try to migrate existing code to the setIndeterminate( method. This 
method may not exist in future versions of ooDialog. 


14.3. CheckBox Class 


Check boxes are similar in many ways to radio buttons. A check box consists of a square box and a 
programmer defined label, icon, or bitmap that indicates to the user a choice. Check boxes are typically 
grouped together as a set of independent options. Checking or unchecking one option usually has no 
effect on the other check box options. 


There are four styles of check boxes: standard, automatic, three-state, and automatic three-state, The 
system manages the check state of automatic and automatic three-state check boxes. All check boxes 
have at least two states, either checked or cleared (unchecked.) In addition three-state check boxes have a 
third state called indeterminate, which the system draws as a grayed box inside the check box. 


Repeatedly clicking standard and automatic check boxes toggles them back and forth from cleared to 
checked, and back again. Doing the same with a three-state check box toggles it from cleared, to 
checked, to indeterminate, and back again. 


The CheckBox class provides methods to query and modify check box controls. 


Requires: 
The CheckBox class requires the class definition file oodWin32.cls : 


::requires "oodWin32.cls" 


Subclass of: 
The check box class is a direct subclass of the RadioButton class, and therefore an indirect subclass 
of the ButtonControl class and the DialogControl class class. It inherits all the methods of all three 
classes. 

Mixin Class Inherits: 


The check box class inherits from the following mixin classes, (indirectly through the 
DialogControl class.) 


The WindowBase 


The WindowExtensions 


Instantiation: 


Use the getCheckControl() method to retrieve an object of the check box class. 
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Dynamic Definition: 
To dynamically define a check box in a UserDialog class, use one of the add button methods 
described in the Add Button Control section. That section also describes methods for adding push 
buttons, radio buttons, etc.. All the methods to add check boxes begin with: addCheck. 

Event Notification 


A check box, is a button, and the programmer uses the same methods to recieve notifications of 
events as with the ButtonControl: the connectButton() method, or the connectButtonNotifyQ 
method. 


Methods: 


The CheckBox class implements the instance methods listed in the following table: 


Table 14-4. CheckBox Instance Methods 














Method... ...Description 
isIndeterminate isIndeterminate 
getCheckState getCheckS tate 
setIndeterminate setIndeterminate 














14.3.1. isindeterminate 
2»--isIndeterminate-----------—-------------4-55c5 >< 
Determines if the check box is in indeterminate state, or not. 
Arguments: 

There are no arguments. 


Return value: 


Returns true if the check box is in the indeterminate state, otherwise false. 


Example: 
This example is from a program that sets the background color to black, white, or gray. 


chkBox = self^getCheckControl(IDC, CHK BACKGROUND) 
if chkBox^isIndeterminate then return self^grayBackground 


14.3.2. getCheckState 


>>--рербнресковане---------ня-я---9яне-я-- ана SS SESS SRR SSS SERS SES >< 


This method over-rides the RadioButton getCheckState() method to return a keyword indicating the 
check state of the check box, checked, unchecked, or indeterminate. 
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Arguments: 


There are no arguments to this method. 


Return value: 


The return value is a keyword indicating the checked state of the check box and will exactly one of 
the following: 


UNCHECKED The check box is not checked. 
CHECKED The check box is checked. 
INDETERMINATE The check box is in the indeterminate state. 
UNKNOWN The object is not a check box. 

Example: 


This example is a variation of the example for the isIndeterminate() method. 


state = self~ getCheckControl (IDC_CHK_BACKGROUND) ~getCheckState 


select 
when state == "CHECKED" then return self~blackBackground 
when state == "UNCHECKED" then return self^whiteBackground 
when state == "INDETERMINATE" then return self^grayBackground 
otherwise nop -- Drop through and do error handling 

end 

-- End select 


14.3.3. setindeterminate 


>>--ве 1 егшпаве-----------<---+--------- >< 


Те setIndeterminate method puts Ше check box in Ше indeterminate state. The system will redraw Ше 
check box to indicate the indeterminate state. 


14.4. GroupBox Class 


The Windows Group Box control is actually a button control, not a static control. Its purpose is to group 
together a set of related controls. It consists of a label and a rectangle. The related controls are placed 
within the rectangle. Group boxes have no state, they can not be selected, and an application can not send 
messages to the control. In addition, a group box does not send notifications to its parent so there are no 
events to connect to a group box. 


The GroupBox class provides methods to work with group box controls. 
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Requires: 
The GroupBoxe class requires the class definition file oodwin32.cls: 


::requires "oodwin32.cls" 


Subclass of: 


Although the group box is a button, since it does not have a state, can not be selected, does not send 
notifications, etc., it does not inherit from the ButtonControl class. A group box does not share 
behaviour or characteristics with the other button classes. Therefore, the group box class is a direct 
subclass of the DialogControl class. It therefore inherits all methods of that class. 

Mixin Class Inherits: 


The group box class inherits from the following mixin classes, (indirectly through the 
DialogControl class.) 


The WindowBase 


The WindowExtensions 


Instantiation: 


Use the getGroupBox() method to retrieve an object of the group box class. 


Dynamic Definition: 


To dynamically define a group box in a UserDialog class, use the addGroupBox() method. 


Event Notification 


Group boxes do not generate notifications. 


Methods: 


The GroupBox class only implements a few methods, (actually only one method at this time.) 


Table 14-5. GroupBox Instance Methods 





Method... ...Description 











style= style= 








14.4.1. Style= 


22--8tylez-styleKeyword--—-—-—----------------———— >< 


Assigns a new text alignment to the group box. By default the text of a group box is in the upper left 
corner. The alignment can also be set to the right, although this is not commonly done. 
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Arguments: 


The only argument is: 


styleKeyword 


A text string that is either: 


LEFT 
The group box label is aligned to the upper left. 


RIGHT 
The label is aligned to the upper right. 


Example: 
Changing the style is staightforward: 


gb = self~getGroupBox (IDC_GB_AREACODES) 
if gb == .Nil then return 
gb^style-"RIGHT" 


14.5. AnimatedButton Class 


The AnimatedButton class provides the methods to implement an animated button within a dialog. The 
attributes and methods are only described briefly in this document. An example program, oowalker.rex, 
is provided with the OODialog sample programs. 


ParentDlg 
Attribute holding the handle of the parent dialog 


Stopped 


Animation ends when set to 1 (see Stop method) 
Init 
Initialize the animation parameters: 


but = .AnimatedButton~new(buttonid,from,to, , 
movex,movey,sizex,sizey,delay, , 
startx,starty,parentdialog) 


The values are stored in a stem variable: 


sprite.buttonid 


ID of animation button 
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sprite.from 
Array of in-memory bitmap handles, or a bitmap resource ID in a DLL, or the name of an array 
in the .local directory containing handles to bitmaps loaded with LoadBitmap. The array has to 
start with 1 and continue in increments by 1. 

sprite.to 
0 if sprite.from is an array, or the name of an array stored in .1ocal, or a bitmap resource ID in 
aDLL 

sprite.movex 


Size of one move horizontally (pixels) 


sprite.movey 


Size of one move vertically 


sprite.sizex 


Horizontal size of all bitmaps (pixels) 


sprite.sizey 


Vertical size of all bitmaps 


sprite.delay 
Time delay between moves (ms) 
Startx and starty are the initial bitmap position, and parentdialog is stored in the ParentDlg attribute. 


Two more values are initialized in the stem variable: 


sprite.smooth 


Set to 1 for smooth edge change (can be changed to 0 for a bouncy edge change) 


sprite.step 


Set to 1 as the step size between sprite.from and sprite.to for bitmaps in a DLL 


SetSprite 
Set all the sprite. animation values using a stem: 


mysprite.from = .array~of(bmp1,bmp2,...) 
mysprite.to = 0 
mysprite.movex =... 


self^setSprite(mysprite.) 


GetSprite 
Retrieve the animation values into a stem: 


self^getSprite(mysprite.) 
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SetFromTo 
Set bitmap information (sprite.from and sprite.to): 


self^setFromTo(bmpfrom,bmpto) 


SetMove 


Set size of one move (sprite.movex and sprite.movey): 


self^setMove(movex,movey) 


SetDelay 
Set delay between moves in milliseconds (sprite.delay): 


self^setDelay(delay) 


SetSmooth 


Set smooth (1) or bouncy (0) edges (sprite.smooth): 


self^setSmooth(smooth) /* 1 or O */ 


setStep 


Set the step size (sprite.step) between sprite.from and sprite.to for bitmaps in a DLL, for example, if 
bitmap resources are numbered 202, 204, 206, etc: 


self^setFromTo(202,210) 
self^setStep(2) 


Run 


Run the animation by going through all the bitmaps repetitively until dialog is stopped; invokes 
MoveSeq: 


self^run 


MoveSeq 


Animate one sequence through all the bitmaps in the given move steps; invokes MovePos: 


self~moveSeq 
MovePos 
Move the bitmaps by the arguments: 
self~movePos (movex ,movey) 
MoveTo 
Move the bitmaps in the predefined steps to the given position; invokes MoveSeq: 
self~moveTo(posx, posy) 


setPos 


Set the new starting position of the bitmaps: 


self^setPos(newx,newy) 
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GetPos 
Retrieve the current position into a stem: 


self^getPos(pos.) 


say "pos-" pos.x pos.y 


ParentStopped 


Check the parent dialog window and return its finished attribute (1 means finished) 


Stop 
Stop animation by setting the stopped attribute to 1 

HitRight 
Invoked by run when the bitmap hits the right edge (returns 1 and bitmap starts at left again; you 
can return 0 and set the new position yourself) 

HitLeft 


Invoked when the bitmap hits the left edge (default action is to start at right again) 


HitBottom 


Invoked when the bitmap hits the bottom edge (default action is to start at top again) 


HitTop 
Invoked when the bitmap hits the top edge (default action is to start at bottom again) 


To use an animated button a dialog has to: 


* Define a button in a resource file (owner-drawn) 

* Load the bitmaps of the animation into memory using an array 
* Initialize the animated button with the animation parameters 

* Invoke the run method of the animated button 

* Stop the animation and remove the bitmaps from memory 


The dialog may also dynamically change the parameters (for example, the size of a move, or the speed) 
and override actions, such as hitting an edge. 


See the oowalker.rex and oowalk2.rex examples in OODIALOG\SAMPLES. 


For further information see ConnectAnimatedButton. 
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The EditControl class provides methods to query and modify edit controls, which are also called entry 
lines in the ooDialog documentation. It inherits all methods of the DialogControl class (see page 
DialogControl Class). 


Use the GetEditControl method (see page GetEditControl) to retrieve an object of the EditControl class. 


Requires: 
The EditControl class requires the class definition file oodwin32.c1s: 
::requires "oodwin32.cls" 

Methods: 


Instances of the EditControl class implement the methods listed in the following EditControl 
Instance Methods table. 


Table 15-1. EditControl Instance Methods 










































































Method... ..оп page 
AddStyle AddStyle 
EnsureCaret Visibility EnsureCaret Visibility 
First VisibleLine FirstVisibleLine 
GetLine GetLine 
GetStyle GetStyle 
GetText GetText 
HideBalloon HideBalloon 
IsModified IsModified 
LineFromIndex LineFromIndex 
LineIndex LineIndex 
LineLength LineLength 
LineScroll LineScroll 
Lines Lines 

Margins Margins 
PasswordChar PasswordChar 
PasswordChar= PasswordChar= 
RemoveStyle RemoveStyle 
ReplaceStyle ReplaceStyle 
ReplaceSelText ReplaceSelText 
ScrollCommand ScrollCommand 
Select Select 

Selected Selected 

SetCue SetCue 
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Method... ..оп page 

SetLimit SetLimit 

SetMargins SetMargins 

SetModified SetModified 

SetReadOnly SetReadOnly 

SetText SetText 

ShowBalloon ShowBalloon 
15.1. Selected 

2-=ankditControl’ бе!есъей-------------------------<--------<- >< 


The Selected method retrieves the indexes of the starting and ending character of the text selected. If the 
starting index equals the ending index, no text is selected and the index specifies the current cursor 
position. If the ending index is 0 and the starting index is 1, the entire text is selected. 


Return value: 


The one-based starting and ending index of the current selection, separated by a blank. 


Example: 


The following example displays the starting and ending index of the text selection of the edit control 
NAME. It then selects the entire text of the edit control. 


edit = MyDialog~GetEditControl ("NAME") 

if edit == .Nil then return 

parse value edit^Selected with start end 
say "Starting index of selection is" start 
say "Ending index of selection is" end 
edit^Select(1,0) 


15.2. Select 


»»-anEditControl^Select(--start--,--end--)--------------------- >< 


The Select method selects the text or sets the cursor position for the associated edit control. If the starting 
index equals the ending index, no text is selected and the cursor is set to the character at the specified 
index. If the ending index is 0 and the starting index is 1, the entire text is selected. 
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Arguments: 
The arguments are: 
start 
A one-based index where the selection begins or the cursor is to be set. 
end 


A one-based index where the selection ends. 


Example: 


See Selected. 


15.3. ScrollCommand 


+-UP-------- + 
»»-anEditControl^ScrollCommand(--"--4----------- *--'"--—4---------------- +--)->< 

T-LEFT------ * *-,--repetitions--* 

*-DOWN------ * 

*-RIGHT----- * 


+-PAGEUP----+ 
+-PAGELEFT--+ 
+-PAGEDOWN--+ 
+-PAGERIGHT-+ 


The ScrollCommand method scrolls the associated edit control in a given direction. 


Arguments: 


The arguments are: 


command 


Specifies the direction and the step size of the scroll command. Possible values are: 


UP or LEFT 


Scrolls up one line. UP is the default. 


DOWN or RIGHT 


Scrolls down one line. 


PAGEUP or PAGELEFT 


Scrolls up one page. 
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PAGEDOWN or PAGERIGHT 


Scrolls down one page. 


repetitions 


The number of times the scroll command is to be issued. If this argument is omitted, the scroll 
command is issued once. 


Example: 


The following example scrolls down 3 lines in the edit control: 


edit = MyDialog~GetEditControl ("NAME") 
if edit == .Nil then return 
edit^ScrollCommand ("DOWN",3) 


15.4. LineScroll 


»»-anEditControl^LineScroll(--sChars--,--sLines--)------------- >< 


The LineScroll method scrolls the text in a multiline edit control vertically or horizontally by the 
specified number of characters and lines. 


Arguments: 


The arguments are: 


sChars 


The number of characters to be scrolled horizontally. 


sLines 


The number of lines to be scrolled vertically. 


Return value: 
О if the message is sent to a multiline edit control, or a non-zero value if the message is sent to a 
single-line edit control. 

Example: 


The following example scrolls an edit control by 50 characters and 35 lines: 


edit^Scroll(50, 35) 


Note: The edit control does not scroll vertically past the last line of text. If the current line, plus the 
number of lines specified by sLines, exceeds the total number of lines in the edit control, the last line 
of the edit control is scrolled to the top. The LineScroll message can, however, be used to scroll 
horizontally past the last character of a line. 
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15.5. EnsureCaretVisibility 


»»-anEditControl^EnsureCaretVisibility------------------------- >< 


The EnsureCaret Visibility method scrolls the edit control until the caret (cursor) is visible. 


Return value: 


О if the object is associated with an existing edit control. 


15.6. FirstVisibleLine 


»»-anEditControl^FirstVisibleLine------------------------------ >< 


The FirstVisibleLine method retrieves the one-based line number of the first line visible in a multiline 
edit control. 


Return value: 


The number of the first visible line, starting with 1. 


Example: 


For an example, refer to PasswordChar=. 


15.7. IsModified 


>>=ankditControl” IsModifiéd-----------—----------------oscee-oo >< 


The IsModified method retrieves information on whether the edit control has been modified. 


Return value: 


The text in the edit control has been altered. 


For all other cases. 
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Example: 
(See also the SetText example.) 


if edit~ IsModified = 1 then MyDialog^Save 


15.8. SetModified 


»»-anEditControl^SetModified(--bool--)------------------------- >< 


The SetModified method sets the flag to indicate whether the edit control has been modified. 


Arguments: 


The only argument is: 


bool 


The flag indicates that the text has been altered. 


For all other cases. 


Example: 


In the following example, the Save method stores the dialog contents in a file and clears the 
modified flag. See also the SetText example. 


::method Save 
/* write contents to file */ 
edit = MyDialog~GetEditControl ("TEXT") 


edit ~SetModified(0) 
15.9. Lines 
>2-апЕ | Control” лпев---------------------<--- >< 


The Lines method retrieves Ше number of text lines of a multiline edit control. 


Return value: 


The number of text lines. 


554 ooRexx OODialog Reference Version 4.0.0 


Chapter 15. EditControl Class 


Example: 


For an example, refer to LineIndex. 


15.10. Linelndex 


»»-anEditControl^LineIndex(--line--)--------------------------- >< 


The LineIndex method retrieves the one-based character index of the beginning of the line in the 
associated edit control. 


Arguments: 


The only argument is: 


line 


The number of the line of which the starting index is to be retrieved. Line numbers are 
incremented by 1, starting with 1. 


Return value: 


The character index of the specified line. The first line starts at index 1. 


Example: 


The following example sets the text for edit control TEXT and displays the number of text lines (3), 
the starting index of the second line (carriage return, OxOd, and line feed, Ох0а, which mark a line 
break, are also considered to be characters), and the length of the third line: 


editControl = MyDialog~GetEditControl ("TEXT") 


if .nil == editControl then return 
text = "It is easy to learn and easy to use." || ?0OdOa?x || - 
"Have fun with it!" || ?Od0a’x || - 


"But don’t over do it." 
edit^setText (text) 
say "Number of lines:" edit^lines 
say "Line 2 begins at index" edit^LineIndex(2) 
say "Length of 3rd line:" edit^LineLength(3) 
Result: Number of lines: 3 


Line 2 begins at index 39 
Length of 3rd line: 21 
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15.11. LineFromlndex 


»»-anEditControl^LineFromIndex(--index--)---------------------- >< 


The LineFromIndex method retrieves the one-based line number that contains the character index index. 


Arguments: 


The only argument is: 


index 


The one-based character index contained in the line whose number is to be retrieved. 


Return value: 
The line number containing the specified character index. The first line starts at index 1. If the 
specified index exceeds the number of characters contained in the edit control or an invalid 
character index was specified, 0 is returned. 

Example: 
The following example displays the line in which character 55 is contained: 


edit = MyDialog~GetEditControl ("ТЕХТ") 
if edit == .Nil then return 


"It is easy to learn and easy to use." || 13^d2c || 10792с |l, 
"Have fun with it!" 


say "Character 55 is contained in line" edit~LineFromIndex(55) 


Result: Character 55 is contained in line 2 


15.12. LineLength 


»»-anEditControl^LineLength(--line--)-------------------------- >< 


The LineLength method retrieves the number of characters contained in the line in the associated edit 
control. 


Arguments: 


The only argument is: 
line 


The number of the line of which the number of characters is to be retrieved. Line numbers are 
incremented by 1, starting with 1. 


556 ooRexx OODialog Reference Version 4.0.0 


Chapter 15. EditControl Class 


Return value: 


The length of the given line. 


Example: 


For an example, refer to LineIndex. 


15.13. GetLine 


»»-anEditControl^GetLine--(--line--4-------------- A >< 
+-,--maxLength-+ 


The GetLine method retrieves the text string contained in the specified line. 


Arguments: 


The arguments are: 


line 


The one-based line number to be retrieved. 


maxLength 


The maximum number of characters to be retrieved. Object Rexx allocates the appropriate 
amount of memory to store the text string. If the line consists of more characters than fit in the 
memory, the text string is truncated. If you omit this argument, the maximum number of 
characters retrieved is 255. 


Return value: 


A text string or an empty string. 


Example: 


The following example stores all lines contained in edit control EDITOR in a stem. If a line consists 
of more than 1024 characters, it is truncated. 


edit = MyDialog~GetEditControl ("EDITOR") 
if edit == .Nil then return 
do i = 1 to edit^Lines 
lines.i = edit~GetLine(i, 1024) 
end 


Note: The carriage return and line-feed characters are not included in the returned text string. To get 
the contents of a single line edit control, use the GetText) method, or use edit~GetLine if there is no 
need to worry about truncation, or use edit^GetLine(1, [maxLength]) if the length of the text is 
greater than 255. 
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15.14. GetText 


>>-ankditControl” GetText--—--—---—------—--— SSS ceci ce >< 


The GetText method returns the entire contents of the text buffer of the edit control as a string. The 
method works the same for both single-line and multi-line edit controls. With multi-line edit controls, the 
returned string will contain the carriage return and line-feed characters present in the text buffer. The 
programmer does not need to worry about the length of the text in the edit control. All the text is returned 
no matter what the length of the text is. 


Return value: 
The text in the edit control. 


Example: 


For an example, refer to the SetText example. 


15.15. SetText 


»»-anEditControl^SetText(--text--)----------------------------- >< 


The SetText method places text in the edit control. Any current text content in the edit control is 
completely replaced. 


Arguments: 


The only argument is: 


text 


The text to be displayed in the edit control. For multi-line edit controls the text must contain 
the carriage return and line-feed characters. 


Return value: 


The return values are: 


No error. 


less than 0 


Error. The value is the negated Operating System Error code. The absolute value of the return 
can be used to look up the error reason in the Windows documentation. 
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Example: 


The following code snippets use the GetText and SetText methods in a dialog that could be used as 
a simple file editor: 


::method defineDialog 


self~addEntryLine(110, , 5, 5, 170, 150, "VSCROLL HSCROLL MULTILINE") 


self^addButton(115, 5, 160, 35, 15, "Open", onOpen) 
self^addButton(116, 45, 160, 35, 15, "Save", onSave) 


::method initDialog 
expose editControl 
editControl = self^getEditControl(110) 


::method опОреп 
expose editControl 


if .nil == editControl then return 


fileName - self^getFile 


if fileName -- "" then return 
fÜbj = .stream^new(fileName) 
fÜbj^open 


if fÜbj^state \== ’READY’ then return 


text = fÜbj^charin(1, f0bj~chars) 
f0bj~ close 


editControl^setText (text) 
editControl^setModified(.false) 


::method onSave 
expose editControl 


if .nil == editControl then return 


if editControl~isModified then do 
text = editControl^getText 
self^saveFile(text) 
editControl^setModified(.false) 
end 
else do 
j = InfoDialog("There is nothing to save") 
end 
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15.16. ReplaceSelText 


>>-anEditControl~ReplaceSelText (--text--)---------------------- >< 


The ReplaceSelText method replaces the selected text in the associated edit control with a new one. 


Arguments: 


The only argument is: 


text 


The text string that is to replace the currently selected text. 


Example: 


edit = MyDialog~GetEditControl ("ТЕХТ") 
if edit == .Nil then return 
edit^Title = "Object Rexx is a hybrid language." 
edit~Select (17,25) 
edit~ReplaceSelText("n interpreted") 
say edit Title 


Result: Object Rexx is an interpreted language. 


15.17. SetLimit 


»»-anEditControl^SetLimit (--chars--)--------------------------- >< 


The SetLimit method sets the maximum numbers of characters that the associated edit control can 


contain. 


Arguments: 


The only argument is: 


chars 


The number of characters that the edit control can contain. 


15.18. PasswordChar= 


»»-anEditControl^PasswordChar---char--------------------------- >< 
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The PasswordChar= method sets the character that is displayed in an edit control for which the 
PASSWORD or ES_PASSWORD flag is set. 


Arguments: 


The only argument is: 


char 


The character that is displayed for the typed characters. 


Example: 


The following example ensures that if the PASSWORD style was chosen for the edit control, the 
dollar sign ($) is displayed for each character typed in the edit control: 


edit = MyDialog~GetEditControl ("TEXT") 
if edit == .Nil then return 
edit~PasswordChar = "$" 


say "The new password character is" edit^PasswordChar 


15.19. PasswordChar 


»»-anEditControl^PasswordChar---------------------------------- >< 


The PasswordChar method retrieves the character that is displayed in an edit control for which the 
PASSWORD option or ES_PASSWORD style was set. 


Return value: 


The character that is displayed instead of the characters contained in the edit control. If the edit 
control is no password field or no password character was set, an empty string is returned. 


Example: 


For an example, refer to PasswordChar=. 


15.20. SetReadOnly 


+-1-+ 
»»-anEditControl^SetReadOnly (--4---4--)------------------------ >< 
+-0-+ 


The SetReadOnly method sets or unsets the read-only flag for the associated edit control. If the read-only 
flag is set, the user can no longer modify the text of the edit control. 
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Arguments: 


The only argument is: 


bool 


1 if the edit control is to be marked as a read-only field (the default), or 0 if new text can be 
typed into the edit control. 


Return value: 


0 if this method was successful. 


15.21. SetMargins 


»»-anEditControl^SetMargins(--left--,--right--)---------------- >< 


The SetMargins method sets the left and right margins for the associated edit control. The margins 
determine the spacing to the left and right of the edit control. 


Arguments: 


The arguments are: 


left 
The left margin, specified in screen pixels. 
right 


The right margin, specified in screen pixels. 


Example: 


The following example sets the margins for edit control TEXT such that the left indent is 10 screen 
pixels and on the right there is a spacing of 5 pixels between the text and the frame of the edit 
control: 


edit = MyDialog~GetEditControl ("TEXT") 
if edit == .Nil then return 
edit^SetMargins(10, 5) 
parse value edit^Margins with left right 
say "The new left margin is" left" and the new right margin is" right 


15.22. Margins 


2»-anEditControl^Margins------------22----2----S------2cem oco = >< 
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The Margins method retrieves the left and right margins of the associated edit control. 


Return value: 


The left and right margins, in screen pixels, separated by a blank. 


Example: 


For an example, refer to SetMargins. 


15.23. SetCue 


»»-anEditControl^SetCue(--text--)------------------------------ >< 


This method sets the "cue" text for an edit control. Cue text provides a visual hint to the user as to the 
purpose of the edit control. When the dialog is first shown to the user the cue text will be displayed, 
(provided there is no text in the edit control’s buffer.) 


The cue text is colored a light grey to distinguish it from regular text. When the edit control gains the 
focus, Windows dismisses the cue text automatically. When the control loses focus, Windows will again 
display the cue text, if the entry control is empty. Once the user has entered text in the edit control, the 
cue is no longer displayed. If the user deletes the text, then the cue is once again displayed when the edit 
control does not have the focus. 


Note: Only single-line edit controls will display cue text. You can not use cue text with a multi-line edit 
control. 


Operating System Version 
This method is only available on Windows XP or later operating systems. If the method is used on 
an unsupported operating system, -4 is returned. 

Arguments: 


The only argument is: 


text 


The text to be displayed to the user as a cue. The maximum length of the text string is 255 
characters. 


Return value: 


The return value will be one of the following: 


less than -4 


The value is the negated Operating System Error code. The absolute value of the return can be 
used to look up the error reason in the Windows documentation. 
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-4 
The operating system does not support this method. Windows XP or later is required. 
-3 
The text argument is too long for this method, or there is an (internal) problem converting the 
text string to Unicode. 
-2 
There is an (internal) problem with the dialog or the dialog handle. 
-1 
There is an (internal) problem with the resource ID or window handle of the edit control. 
0 
The method succeeded. 
1 
The method failed. 
Example: 


For an example see the ShowBalloon example. 


15.24. ShowBalloon 


>>-anEditControl~ShowBalloon(--title,--text--+---------- +--)--->< 
+---1соп--+ 


Displays a balloon information window. Balloon windows are similar in appearance to the balloon 
captions used in comic books to display the dialog of the characters. For an edit control the balloon 
window looks like it is attached to the control. 


The balloon is displayed for 10 seconds and then goes away. The programmer can also dismiss the 
balloon sooner using the HideBalloon method. Typically balloon windows are used to convey 
information to the user without having to put up a message box that the user then needs to dismiss 
manually. 


Operating System Version 


This method is only available on Windows XP or later operating systems. If the method is used on 
an unsupported operating system, -4 is returned. 
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Arguments: 


The arguments are: 


title 


A title for the balloon window. Titles are limited to 99 characters total in length. 


text 
The text of the balloon window. This text is limited to 1024 characters in length. The 
programmer can use line break characters to control the formatting of the text. 

icon 


Used to specify which icon is displayed on the title line. The default is the informational icon. 
The following keywords can be used to specify another icon, or no icon. Only the first letter of 
the keyword is needed and case is insignificant: 


ERROR 


The error icon is used. 


WARN 


The warning icon is used. 


NONE 
No icon is displayed. 


Return value: 


The return value will be one of the following: 


less than -4 


The value is the negated Operating System Error code. The absolute value of the return can be 
used to look up the error reason in the Windows documentation. 


-4 
The operating system does not support this method. Windows XP or later is required. 
-3 
The title or text arguments are too long for this method, or there is an (internal) problem 
converting one of the strings to Unicode. 
-2 
There is an (internal) problem with the dialog or the dialog handle. 
-1 


There is ап (internal) problem with Ше resource ID or window handle of the edit control. 
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0 
The method succeeded. 
1 
The method failed. 
Example: 


The following code snippet could come from a fictitious inventory program. An edit control is used 
to enter a product ID. If the user clicks on the edit control a ballon tip is shown displaying extended 
product information. (In a real application, the extended information might be based on what the 
user had entered in the edit control.) 


Text is set in the edit control to give the user a ’cue’ that she can click on the edit control for extra 
information. When the ballon tip is shown, it will automatically be dismissed after 10 seconds. This 
application connects a notification for the lost focus event. When the edit control loses focus, the 
ballon tip is hidden by the program. 


::method defineDialog 


self~addText(10, 125, 150, 10, "Enter product ID:", "", 200) 
self~addEntryLine(IDC_ENTRYLINE, "cEntry", 10, 135, 150, 10, "AUTOSCROLLH") 


::method initDialog 
expose editControl hwndEditControl 


editControl = self^getEditControl(IDC, ENTRYLINE) 
hwndEditControl = self~getItem(IDC_ENTRYLINE) 


self~connectEditNotify(IDC_ENTRYLINE, GOTFOCUS, "onFocus") 
self^connectEditNotify (IDC ENTRYLINE, LOSTFOCUS, "onLostFocus") 


ret - editControl^setCue("Click here for extended product information") 
if ret <> 0 then ErrorDialog( "Set cue error return:" ret ) 


-- Capture the mouse activate messages: WM MOUSEACTIVATE message -- Ox0021 
self^addUserMsg(onMouseActivate, "0x0021", "OxFFFFFFFF", 0, 0, 0, 0) 


::method onMouseActivate 
expose editControl hwndEditControl 


if self^getFocus == hwndEditControl then do 


title = "Extended Product Information" 
text = "Product ID:" || "9"x || "4538-D32" || .endOfLine || - 
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"In stock:" || "9"x || "789" || .endOfLine || - 
"Back ordered:" || "9"x || "No" || .endOfLine || - 
"EOL:" || "0909"x || "January 2008" || .endOfLine || - 
"Client:" || "0909"x || "AT&T" || .endOfLine || .endOfLine - 


"Notes: This product has served a limited number of customers" - 
"and should be considered archic. Тї will be replaced by a" = 
"superior product line." 


ret = editControl^showBalloon(title, text, "e"); 
if ret <> 0 then ErrorDialog("Show balloon error return:" ret) 
end 


::method onLostFocus 
expose editControl 


-- When the edit control loses the focus, dismiss the alloon. 


ret = editControl^hideBalloon 
if ret <> 0 then ErrorDialog("Hide balloon error return:" ret) 


15.25. HideBalloon 


»»-anEditControl^HideBalloon----------------------------------- >< 


Hides the balloon information window displayed by the ShowBalloon method. The operating system will 
dismiss the balloon window automatically after 10 seconds with no programmer intervention. This 
method can is used to dismiss the ballon sooner. 


Operating System Version 


This method is only available on Windows XP or later operating systems. If the method is used on 
an unsupported operating system, -4 is returned. 


Arguments: 


This method takes no arguments. 


Return value: 


The retrun value will be one of the following: 


less than -4 


The value is the negated Operating System Error code. The absolute value of the return can be 
used to look up the error reason in the Windows documentation. 


The operating system does not support this method. Windows XP or later is required. 


There is an (internal) problem with the dialog or the dialog handle. 
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-1 
There is an (internal) problem with the resource ID or window handle of the edit control. 
0 
The method succeeded. 
1 
The method failed. 
Example: 


For an example see the ShowBalloon example. 


15.26. AddStyle 


+---------------- + 
ү | 
>>-anEditControl~AddStyle (--"---+-UPPER------ +-+--"--)--------- >< 
*-LOWER------ * 
*-NUMBER----- * 
+-WANTRETURN-+ 
+-0ЕМ-------- + 
+-ТАВ-------- + 
*-GROUP------ * 


Adds one or more edit control styles to the edit control. This method works with the window styles that 
can be changed by accessing the edit control window directly after the edit control has been created. 


Arguments: 


The style argument can be one or more of the following keywords. (Each keyword is separated by a 
blank.): 


UPPER 


Converts all characters to uppercase as they are typed into the edit control. 


LOWER 


Converts all characters to lowercase as they are typed into the edit control. 


NUMBER 


Only allows digits to be typed into the edit control. If the user types an non-digit character an 
information balloon is displayed informing the user that only digits are allowd. This style does 
not prevent the user from pasting non-digits into the control. 
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WANTRETURN 


This keyword only effects multi-line edit controls. With this style when a user hits the enter 
key the line break characters are inserted into the text buffer. Without the style, when the user 
hits enter the default push button of the dialog is pressed. 


OEM 


Converts text entered in the edit control from the Windows character set to the OEM character 
set and then back again to the Windows character set. This ensures proper character conversion 
in certain circumstances. Microsoft states that this style is most useful when edit controls 
contain file names that will be used with file systems that do not support Unicode. For further 
details see the Windows documentation provided by Microsoft. 


TAB 
Adds the tabstop tab stop style. 


GROUP 
Adds the group style. 


Return value: 


Negative values indicate error, non-negative values indicate success. 


-4 or less 


The value is the negated Operating System Error code. The absolute value of the return can be 
used to look up the error reason in the Windows documentation. 


The was no valid keyword in the style argument. Note that if the style argument contains at 
least one valid keyword other invalid keywords are then ignored. 


-2 


There is an (internal) problem with the dialog or the dialog handle. 


There is an (internal) problem with the resource ID or window handle of the edit control. 


other 


The numeric value of the edit control’s previous style. 


Example: 


This example shows the syntax to add the number, tabstop, and group styles to an edit control. 


editControl = dlg^getEditControl(IDC ENTRYLINE) 
if .nil == editControl then return 
editControl~addStyle("NUMBER TAB GROUP") 
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15.27. RemoveStyle 


+---------------- + 
ү | 
»»-anEditControl^RemoveStyle(--"---4-UPPER------ +-+--"--)------ >< 
*-LOWER------ * 
*-NUMBER----- * 
+-WANTRETURN-+ 
*-ÜEM-------- * 
*-TAB-------- * 
+-GROUP------ + 


Remove one or more edit control styles from the edit control. This method works with the window styles 
that can be changed by accessing the edit control window directly after the edit control has been created. 


Arguments: 


The style argument can be one or more of the style keywords. (Each keyword is separated by a 
blank.) See the argument list for the AddStyle method for detals on the keywords. 


Return value: 


Negative values indicate error, non-negative values indicate success. 


-4 or less 


The value is the negated Operating System Error code. The absolute value of the return can be 
used to look up the error reason in the Windows documentation. 


-3 
The was no valid keyword in the style argument. Note that if the style argument contains at 
least one valid keyword other invalid keywords are then ignored. 
-2 
There is an (internal) problem with the dialog or the dialog handle. 
-1 
There is an (internal) problem with the resource ID or window handle of the edit control. 
other 
The numeric value of the edit control’s previous style. 


Example: 


This example shows the syntax to remove the lower and the tabstop styles from an edit control. 


editControl = dlg^getEditControl(IDC ENTRYLINE) 
if .nil == editControl then return 
editControl~removeStyle("LOWER GROUP") 
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+-NUMBER----+ 
+-WANTRETURN+ 


Removes and adds edit control styles for the edit control in one operation. This method works with the 
window styles that can be changed by accessing the edit control window directly after the edit control 


has been created. 


Arguments: 


The two arguments can be one or more of the style keywords. (Each keyword is separated by a 
blank.) See the argument list for Ше AddStyle method for detals on the keywords. 


remove 


The first argument is the list of styles to remove. 


add 


The second argument is the list of styles to add. 


Return value: 


Negative values indicate error, non-negative values indicate success. 


-4 or less 


The value is the negated Operating System Error code. The absolute value of the return can be 
used to look up the error reason in the Windows documentation. 


The was no valid keyword in one or both of the style arguments. Note that if a style argument 
contains at least one valid keyword other invalid keywords are then ignored. 


-2 


There is an (internal) problem with the dialog or the dialog handle. 


There is an (internal) problem with the resource ID or window handle of the edit control. 


other 


The numeric value of the edit control’s previous style. 


ooRexx OODialog Reference Version 4.0.0 


Chapter 15. EditControl Class 


Example: 


The following would change an edit control from one that only allows numbers to one that 
uppercases all letters entered, while removing the tabstop style and adding the group style. 


editControl = dlg^getEditControl(IDC ENTRYLINE) 
if .nil == editControl then return 
editControl~replaceStyle("NUMBER TAB", "UPPER GROUP") 


15.29. GetStyle 


22»-anEdrtOControl "Getoty lenses sa Sasser Se ыз ен SSSR SSS SSS SS SSS SSS >< 


Returns the edit control’s current style as a blank delimited list of style keywords. 


Arguments: 


The method takes no arguments. 


Return value: 


A string consisting of blank delimited style keywords. The possible keywords are: VISIBLE 
HIDDEN TAB NOTAB DISABLED ENABLED GROUP HSCROLL VSCROLL PASSWORD 
MULTILINE AUTOSCROLLH AUTOSCROLLV READONLY WANTRETURN 
KEEPSELECTION UPPER LOWER NUMBER OEM RIGHT CENTER LEFT. The meaning of 
these style keywords is documented in the addEntryLine method. 


In addition, if there is an internal error, it is possible that a negative error code might be returned. 
These error codes are documented here, but it is unlikely that the ooDialog programmer would ever 
see them. 


-3 or less 


The value is the negated Operating System Error code. The absolute value of the return can be 
used to look up the error reason in the Windows documentation. 


-2 
There is an (internal) problem with the dialog or the dialog handle. 
-1 
There is an (internal) problem with the resource ID or window handle of the edit control. 
Example: 


The following example could be from a fictitious application that changes the style of an edit 
control back and forth between accepting numbers only and accepting all characters based on the 
options the user has selected. 


editControl = dlg^getEditControl(IDC ENTRYLINE) 
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if .nil == editControl then return 

style = editControl^getStyle 

if style^wordPos("NUMBER") <> 0 then 
editControl~removeStyle ("NUMBER") 
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There are 3 types of combo boxes. 


* Simple combo boxes 
* Drop-down combo boxes 
* Drop-down list boxes 


A combo box consists of a list and a selection field. The list presents options that can be selected and the 
selection field displays the current selection. 


In simple and drop-down combo boxes the selection field is an edit control and can be used to enter text 
not available in the list, or to edit existing text. In drop-down list combo boxes, the list is a list box 
control and the use can only select the items. In a drop-down combo-box the list only appears when the 
user opens it. In a simple combo box the list is always visible. 


The ComboBox class provides methods to query and modify combo box controls. It inherits all methods 
of the DialogControl class (see DialogControl Class) 


Use the GetComboBox method (see GetComboBox) to retrieve an object of the ComboBox class. 


Requires: 
The ComboBox class requires the class definition file oodwin32.cls: 
::requires "oodwin32.cls" 

Methods: 


Instances of the ComboBox class implement the methods listed in the ComboBox Instance Methods 
table. 


Table 16-1. ComboBox Instance Methods 















































Method... ..оп page 

Add Add 
AddDirectory AddDirectory 
CloseDropDown CloseDropDown 
Delete Delete 

DeleteAll DeleteAll 
EditSelection EditSelection 
Find Find 

GetText GetText 

Insert Insert 
IsDropDownOpen IsDropDownOpen 
Items Items 

Modify Modify 
OpenDropDown OpenDropDown 
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Method... ..оп page 
Select Select 
SelectIndex SelectIndex 
Selected Selected 
SelectedIndex SelectedIndex 





16.1. Add 


»»-aComboBox^Add(--listEntry--)-------------------------------- >< 


The Add method adds a new item to the list of the combo box. If the list is not sorted, the new item is 
added to the end of the list. 


Arguments: 


The only argument is: 


listEntry 


A text string added to the list. 


Return value: 


A one-based index that specifies the position at which the entry has been added, or 0 or a value less 
than 0 to indicate an error. 


16.2. Insert 


»»-aComboBox^Insert(--4------- *--,--listEntry--)--------------- >< 
+-іпаех-+ 


The Insert method inserts а new item into the list of the combo box after the specified item. 


Arguments: 


The arguments are: 


index 


The index (starting with 1) of the list item after which the new item is to be added. If this 
argument is omitted, the list entry is added after the currently selected item. 
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listEntry 


A text string added to the list. 


Return value: 


A one-based index that specifies the position at which the entry has been added, or 0 or a value less 
than 0 to indicate an error. 


16.3. Delete 


»»-aComboBox^Delete(--index--)--------------------------------- >< 


The Delete method removes a list item from the associated combo box. 


Arguments: 


The only argument is: 


index 


The index (starting with 1) of the list item to be removed from the list. If this argument is 
omitted, the currently selected item is deleted. 


Return value: 


The number of remaining list items, or 0 to indicate an error. 


16.4. DeleteAll 


»»-aComboBox^DeleteAll----------------------------------------- >< 


The DeleteAll method removes all list items from the associated combo box. 


Arguments: 


The only argument is: 


index 


The index (starting with 1) of the list item to be removed from the list. If this argument is 
omitted, the currently selected item is deleted. 


Return value: 


The number of remaining list items, or 0 to indicate an error. 
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16.5. Find 


»»-aComboBox^Find(--TextorPrefix--4--------------------------------- +--)->< 
+-,--+------------ +--+---------- +-+ 


И 


+-startIndex-+ +-,--exact-+ 


The Find method searches the combo box for a list entry containing the specified text or prefix. The 
search is caseless. 


Arguments: 


The arguments are: 
TextorPrefix 
The text or prefix for which the list is searched. 


startIndex 


The first list item at which the search is to be started. When the search reaches the bottom of the 
list, it is continued backward. If you omit this argument or specify 0, the entire list is searched. 


exact 


If you specify 1 or E, the text of the list item must exactly match the text specified for 
TextorPrefix. If you omit this argument or specify 0, the list entries are searched for a prefix 
that matches TextorPrefix. 


Return value: 


The one-based index of the list entry that matches the search text, or 0 if not found. 


16.6. Selectedindex 


»»-aComboBox^SelectedIndex------------------------------------- >< 


The SelectedIndex method retrieves the index of the currently selected entry of the combo box list. This 
entry is highlighted and surrounded by a dotted border. 


Return value: 


The one-based index of the currently selected list entry, or 0 if none is selected. 


16.7. Selected 


2»-aComboBox ветесъед-------------- 5 ----<+-+-----------+--<-<- >< 
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The Selected method retrieves the text of the currently selected entry of the combo box list. 


Return value: 


The text of the currently selected list entry, or an empty string if none is selected. 


16.8. Selectindex 


»»-aComboBox^SelectIndex(--index--)---------------------------- >< 


The SelectIndex method selects the list entry at the specified position. The currently selected list item in 
the combo box is highlighted and surrounded by a dotted border. 


Arguments: 


The only argument is: 


index 


The index (starting with 1) of the list item to be selected. If you specify 0 for this argument, the 
combo box must not contain any selection. 


Return value: 


0 if an error occurred or you specified 0 for index to remove the selection. 


16.9. Select 


»»-aComboBox^Select(--ItemText--)------------------------------ >< 


The Select method selects the list entry that matches the specified text. 


Arguments: 


The only argument is: 


ItemText 


The text that the combo box is searched for. 


Return value: 


О if an error occurred or a matching list entry was not found. 
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16.10. Items 


22-aComboBox- tems ss 42444 9 aCe SSS ыш зш ы сыны ты ша ы нышы >< 


The Items method retrieves the number of items in the combo box. 


Return value: 


The number of items in the combo box list. 


16.11. GetText 


»»-aComboBox^GetText (--index--)-------------------------------- >< 


The GetText method gets the text of the list item at the specified position in the combo box. 


Arguments: 


The only argument is: 


index 


The one-based index of the combo box item containing the text you are interested in. 


Return value: 


The text of the combo box item at the given position, or an empty string if the index does not refer 
to an item or an error occurred. 


16.12. Modify 


>>-aComboBox~Modify(--index-- ,--newText--) --------------------- >< 


The Modify method changes the text of the list item at the specified position in the combo box. 


Arguments: 


The arguments are: 


index 


The one-based index of the combo box item of which the text is to be changed. If you omit this 
argument, the currently selected item is modified. 
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newText 


The new text string to be displayed at the given position. 


Return value: 


The one-based index of the modified combo box item at the given position. The return value is 0 if 
an error occurred, or -1 if the index does not refer to an item. 


16.13. AddDirectory 


>>-aComboBox~ AddDirectory (--drvPath-- ,--"----+-READWRITE-+-+--"--) ->< 
+-READONLY--+ 
+-HIDDEN----+ 
+-SYSTEM----+ 
+-DIRECTORY-+ 
+-АВСНТУЕ---+ 


The AddDirectory method adds all or selected file names of a given directory to Ше combo box. 


Arguments: 


The arguments are: 


drvpath 


The drive, path, and name pattern. 


fileAttributes 


Specify the file attributes the files must possess in order to be added: 


READWRITE 


Normal read/write files (same as none). 


READONLY 


Files that have the read-only bit. 


HIDDEN 
Files that have the hidden bit. 


SYSTEM 


Files that have the system bit. 


DIRECTORY 


Files that have the directory bit. 
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ARCHIVE 


Files that have the archive bit. 


Return value: 


The one-based index of the file name added last to the list, or 0 if an error occurred. 


Example: 


The following example puts the names of all read/write files with extension .REX in the given 
directory of the list box: 


MyDialog^AddDirectory(203, drive":\"path"\*.rex", "READWRITE") 


16.14. OpenDropDown 


»»-aComboBox^ÜpenDropDown-------------------------------------- >< 


The OpenDropDown method opens the list box of the associated combo box. 


16.15. CloseDropDown 


»»-aComboBox^CloseDropDown------------------------------------- >< 


The CloseDropDown method closes the list box of the associated combo box. 


16.16. IsDropDownOpen 


»»-aComboBox^IsDropDownÜpen------------------------------------ >< 


The IsDropDownOpen method retrieves whether the list box of the associated combo box is open, that is, 
visible. 


Return value: 


The list box is open. 
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For all other cases. 


16.17. EditSelection 


»»-aComboBox^EditSelection(--startNdx--,--endNdx--)------------ >< 


The EditSelection method selects the specified text range in the edit control of the associated combo box. 


Arguments: 


The arguments are: 


startNdx 


The one-based index of the first character in the edit control to be selected. If you omit this 
argument or specify 0, the selection is removed. 


endNdx 


The one-based index of the last character in the edit control to be selected. If you omit this 
argument or specify 0, the selection is removed. 


Return value: 


The selection was successful. 


An error occurred. 
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The ListBox class provides methods to query and modify list box controls. It inherits all methods of the 
DialogControl class (see page DialogControl Class). 


Use the GetListBox method (see page GetListBox) to retrieve an object of the ListBox class. 


Requires: 
The ListBox class requires the class definition file oodwin32.cls: 


::requires "oodwin32.cls" 


Methods: 


Instances of the ListBox class implement the methods listed in the ListBox Instance Methods table. 


Table 17-1. ListBox Instance Methods 






















































































Method... ..оп page 
Add Add 
AddDirectory AddDirectory 
ColumnWidth ColumnWidth 
Delete Delete 
DeleteAll DeleteAll 
DeSelectIndex DeSelectIndex 
DeselectRange DeselectRange 
Find Find 
GetFirstVisible GetFirstVisible 
GetText GetText 

Insert Insert 
ItemHeight ItemHeight 
ItemHeight- ItemHeight= 
Items Items 
MakeFirst Visible MakeFirst Visible 
Modify Modify 

Select Select 

Selected Selected 
SelectedIndex SelectedIndex 
SelectedIndexes SelectedIndexes 
SelectedItems SelectedItems 
SelectIndex SelectIndex 
SelectRange SelectRange 
SetTabulators SetTabulators 
SetWidth Set Width 
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Method... ..оп page 
Width Width 

















17.1. Add 


»»-aListBox^Add(--listEntry--)--------------------------------- >< 


The Add method adds a new item to the list. If the list is not sorted, the new item is added to the end of 
the list. 


Arguments: 


The only argument is: 


listEntry 


A text string added to the list. 


Return value: 


A one-based index that specifies the position at which the entry has been added, or 0 or a value less 
than 0 to indicate an error. 


17.2. Insert 


>>-aListBox~ Insert (--+------- *--,--listEntry--)---------------- >< 
+-1пдех-+ 


The Insert method inserts a new item into Ше list after the specified item. 


Arguments: 


The arguments are: 


index 


The index (starting with 1) of the list item after which the new item is to be added. If this 
argument is omitted, the list entry is added after the currently selected item. 


listEntry 


A text string added to the list. 


586 ooRexx OODialog Reference Version 4.0.0 


Chapter 17. ListBox Class 


Return value: 


A one-based index that specifies the position at which the entry has been added, or 0 or a value less 
than 0 to indicate an error. 


17.3. Delete 


»»-aListBox^Delete(--4------- *--)------------------------------ >< 
+-index-+ 


The Delete method removes a list item from the associated list box. 


Arguments: 


The only argument is: 


index 


The index (starting with 1) of the list item to be removed from the list. If this argument is 
omitted, the currently selected item is deleted. 


Return value: 


The number of remaining list items, or 0 to indicate an error. 


17.4. DeleteAll 


>>=ат^сВох-ШЮе1евд11============— == озчу наета ня >< 


The DeleteAll method removes all list items from the associated list box. 


17.5. Find 


»»-aListBox^Find(--TextorPrefix--4--------------------------------- +--)->< 
+-,--+------------ +--+---------- +-+ 


+-startIndex-+ +-,--exact-+ 


The Find method searches the list box for a list entry containing the specified text or prefix. The search is 
caseless. 
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Arguments: 
The arguments are: 
TextorPrefix 
The text or prefix for which the list is searched. 


startIndex 


The first list item at which the search is to be started. When the search reaches the bottom of the 
list, it is continued backward. If you omit this argument or specify 0, the entire list is searched. 


exact 


If you specify 1 or E, the text of the list item must exactly match the text specified for 
TextorPrefix. If you omit this argument or specify 0, the list entries are searched for a prefix 
that matches TextorPrefix. 


Return value: 


The one-based index of the list entry that matches the search text, or 0 if not found. 


17.6. Selectedindex 


22o-aListBox бейесъейтпдех---------<-5н------- 5 ------------- >< 


The SelectedIndex method retrieves Ше index of the currently selected list entry. This entry is 
highlighted and surrounded by a dotted border. To get the selected items for a multiple selection listbox, 
use GetMultiList; see GetMultiList. 


Return value: 


The one-based index of the currently selected list entry, or 0 if none is selected. 


17.7. Selected 


22-aListBox Selected-----——-——---------ece SSeS SSS Seas esses ышын: >< 


The Selected method retrieves the text of the currently selected list entry. 


Return value: 


The text of the currently selected list entry, or an empty string if none is selected. 
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17.8. Selectindex 


»»-aListBox^SelectIndex(--index--)----------------------------- >< 


The SelectIndex method selects the list entry at the specified position. The currently selected list item is 
highlighted and surrounded by a dotted border. To select multiple items of a multiple selection listbox, 
use SetMultiList; see SetMultiList. 


Arguments: 


The only argument is: 


index 


The index (starting with 1) of the list item to be selected. If you specify 0 for this argument, the 
list box must not contain any selection. 


Return value: 


0 if an error occurred or you specified 0 for index to remove the selection. 


17.9. DeSelectindex 


»»-aListBox^DeSelectIndex(--4------- +=) ----------------------- >< 
+-іпаех-+ 


The DeSelectIndex method deselects the list entry at the specified position for multiple selection 
listboxes. The currently selected list item is highlighted and surrounded by a dotted border. 


Arguments: 


The only argument is: 


index 


The index (starting with 1) of the list item to be deselected. If you specify no index or 0 for this 
argument, all items are deselected. 


Return value: 


-] if an error occurred. 


17.10. Select 


»»-aListBox^Select(--ItemText--)------------------------------- >< 
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The Select method selects the list entry that matches the specified text. 


Arguments: 


The only argument is: 


ItemText 


The text that the list box is searched for. 


Return value: 


О if an error occurred or a matching list entry was not found. 


17.11. SelectRange 


»»-aListBox^SelectRange(--4----------------------------- +--)--->< 
*-startIndex--*------------- +-+ 


+-,--endIndex-+ 


The SelectRange method selects one or more consecutive items of the associated multiselection list box. 


Arguments: 


The arguments are: 


startIndex 


The position of the first list item to be selected. If this argument is omitted, the selection range 
starts with the first item in the list. 


endIndex 


The position of the last list item to be selected. If this argument is omitted, the selection range 
ends with the last item in the list. 


If startIndex is equal to endIndex, a single item of the list is selected. 
Return value: 

-] if an error occurred. This can happen, for example, if the list box is not a multiselection list box. 
Example: 


The following example selects the items 5 through 9: 


lb = self^GetListBox("Offers") 
if lb -- .Nil then return 
lb^SelectRange(5,9) 
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17.12. DeselectRange 


»»-aListBox^DeselectRange(--4----------------------------- +--)->< 
+-ѕбагіІпаех--+------------- +-+ 
+-,--endIndex-+ 


The DeselectRange method removes the selection for one or more consecutive items of the associated 
multiselection list box. 


Arguments: 


The arguments are: 


startIndex 


The position of the first list item to be deselected. If this argument is omitted, the deselection 
range starts with the first item in the list. 


endIndex 


The position of the last list item to be deselected. If this argument is omitted, the deselection 
range ends with the last item in the list. 


If startIndex is equal to endIndex, a single item of the list is deselected. 


Return value: 


-] if an error occurred. This can happen, for example, if the list box is no multiselection list box. 


Example: 


The following example deselects the items 1 through 5: 


lb = self^GetListBox("Offers") 
if lb == .Nil then return 
lb^DeselectRange(,6) 


17.13. Items 


>> -агав | Вож 1Оёшв-====-—====ш==з=з==ыш зурлы аянтын ыны >< 


The Items method retrieves the number of items in the list box. 


Return value: 


The number of items in the list box. 
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17.14. Selecteditems 


2»-aListBox SelectedTtems---—-------------—--———---ce-ee уы ы ыша >< 


The SelectedItems method retrieves the number of items that are currently selected in the associated 
multiselection list box. 


Return value: 
The number of selected items, or -1 if this method fails, for example if the list box is no 
multiselection list box. 

Example: 


For an example, refer to SelectedIndexes. 


17.15. Selectedindexes 


»»-aListBox^SelectedIndexes------------------------------------ >< 


The SelectedIndexes method retrieves the indexes of all items that are currently selected in the associated 
multiselection list box. 


Return value: 


A text string containing the indexes of the selected items in the list, separated by blanks. 


Example: 


The following example lists all items selected in the associated multiselection list box: 


lb = self^GetListBox("Offers") 
if lb -- .Nil then return 
sit = lb^SelectedItems 
if sit > 0 then do 
say "You ordered:" 
sndx = lb^SelectedIndexes 
do i = 1 to sit 
parse var sndx order sndx 
say "1 x" lb^GetText (order) 
end 
end 


17.16. MakeFirstVisible 


»»-aListBox^MakeFirstVisible(--index--)------------------------ >< 
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The MakeFirstVisible method makes the list entry at the specified position the first visible list item when 
you scroll up or down. 


Arguments: 


The only argument is: 


index 


The one-based index of the list box item to be made first visible. 


Return value: 


-] if an error occurred. 


17.17. GetFirstVisible 


>>-aListBox” GetFirstVisible------------------------------------ >< 


The GetFirst Visible method retrieves the index of the first list item visible in the list box. 


Return value: 


The one-based index of the list box item visible first. 


17.18. GetText 


>>-aListBox~GetText (--index--)--------------------------------- >< 


The GetText method gets the text of the list item at the specified position in the list box. 


Arguments: 


The only argument is: 


index 


The one-based index of the list box item containing the text you are interested in. 
Return value: 


The text of the list box item at the given position, or an empty string if the index does not refer to an 
item or an error occurred. 
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17.19. Modify 


»»-aListBox^Modify(--4------- *--,--newText--)------------------ >< 
+-index-+ 


The Modify method changes the text of the list item at the specified position in the list box. 


Arguments: 


The arguments are: 


index 
The one-based index of the list box item of which the text is to be changed. If you omit this 
argument, the currently selected item is modified. 

newText 


The new text string to be displayed at the given position. 


Return value: 


The one-based index of the modified list box item at the given position. The return value is 0 if an 
error occurred, or -1 if the index does not refer to an item. 


17.20. SetTabulators 


V | 
»»-aListBox^SetTabulators(----tabPos-4--)---------------------- >< 


The SetTabulators method sets the tabulators for the associated list box control. This enables you to use 
items containing tab characters ("09"x), which is useful if you want to format the list in more than one 
column when using proportional fonts. 


Arguments: 


The only argument is: 


tabPos 


The position or positions of the tabs relative to the left edge of the list box, in dialog units. 


Return value: 


1 if an error occurred. 
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Example: 


The following example creates a list that can handle up to three tabulators in a list entry. The 
tabulator positions are 10, 20, and 30. 


lb = MyDialog~GetListBox (102) 


if lb == .Nil then return 

lb^SetTabulators(10, 20, 30) 

lb^Add(textcoli || "O9"x || textcol2 || "09"x || textcol3 || "09"x ||, 
textcol4) 


17.21. AddDirectory 


»»-aListBox^AddDirectory(--drvPath--,--'"----4-READWRITE-4-4--"--)-»« 
+-READONLY--+ 
+-HIDDEN----+ 
+-SYSTEM----+ 
+-DIRECTORY-+ 
+-ARCHIVE---+ 


The AddDirectory method adds all or selected file names of a given directory to the list box. 


Arguments: 


The arguments are: 


drvpath 


The drive, path, and name pattern. 


fileAttributes 


The attributes that the files must have in order to be added: 


READWRITE 


Normal read/write files (same as none). 


READONLY 


Files that have the read-only bit. 


HIDDEN 
Files that have the hidden bit. 


SYSTEM 


Files that have the system bit. 
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DIRECTORY 


Files that have the directory bit. 


ARCHIVE 


Files that have the archive bit. 


Return value: 


The one-based index of the file added last to the list, or O if an error occurred. 


Example: 


The following example puts the names of all read/write files with extension .REX in the given 
directory of the list box: 


MyDialog^AddDirectory(203, drive":\"path"\*.rex", "READWRITE") 


17.22. SetWidth 


»»-aListBox^SetWidth(--width--)-------------------------------- >< 


The SetWidth method sets the internal width of the list box, in dialog units. If the internal width exceeds 
the width of the list box control and the list box has the HSCROLL style, the list box provides a 
horizontal scroll bar. 


Arguments: 


The only argument is: 


width 


The width of the list box, in dialog units. 


Example: 
The following example sets the internal width twice the width of the list box control: 


lb = MyDialog~GetListBox (102) 
if lb == .Nil then return 
lb^SetWidth(lb^SizeX*2) 


17.23. Width 


22-aListBox' Width=--——= театър с >< 


The Width method retrieves the internal width of the associated list box. 
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Return value: 


The internal width of the list box, in dialog units, or 0 if an error occurred. 


17.24. ItemHeight 


s»-aListBox' ТБешНетръб------<-<<-- не-е-е тт еее сее >< 


The ItemHeight method retrieves Ше height of the items in the list box, in dialog units. 


Return value: 


The height of the list box items, in dialog units. 


17.25. ItemHeight- 


>>-aListBox” ItemHeight---height-------------------------------- >< 


The ItemHeight= method sets the height of the items in the list box, in dialog units. 


Arguments: 


The only argument is: 


height 


The height of all list box items, in dialog units. 


17.26. ColumnWidthz 


»»-aListBox^ColumnWidth---width-------------------------------- >< 


The ColumnWidth= method sets the width of the list box columns in a multicolumn list box control. 


Arguments: 


The only argument is: 


width 


The width of all list box columns, in dialog units. 
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The ScrollBar class provides methods to query and modify scroll bars. It inherits all methods of the 
DialogControl class (see page DialogControl Class). 


Use the GetScrollBar method to retrieve an object of the ScrollBar class. 


Requires: 
The ScrollBar class requires the class definition file oodwin32.cls: 
::requires "oodwin32.cls" 

Methods: 


Instances of the ScrollBar class implement the methods listed in the ScrollBar Instance Methods 
table. 


Table 18-1. ScrollBar Instance Methods 




















Method... ..оп page 
DeterminePosition DeterminePosition 
Position Position 

Range Range 

setRange setRange 

setPos setPos 














18.1. setRange 


»»-aScrollBar^sethRange(--min--,--max--4----------- 4--)--------- >< 
+-,--redraw-+ 


The setRange method sets the minimum and maximum positions for the associated scroll bar. 


Arguments: 
The arguments are: 
min 
The minimum position to which the scroll bar can be moved. 


max 


The maximum position to which the scroll bar can be moved. 
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redraw 


If you specify 1 or Y, the scroll bar is redrawn using the new range. Otherwise, the range is set 
but the scroll bar display is not updated. The default value is 1. 


Return value: 


Setting the range was successful. 


For all other cases. 


18.2. Range 


2»-a5crollBar Ranges=—=- HSS SSeS ass шлш ыы сыш + шины ры ыы шт ыш >< 


The Range method retrieves the minimum and maximum positions of the associated scroll bar. 


Return value: 


The minimum and maximum positions, separated by a blank. 


18.3. setPos 


»»-aScrollBar^setPos(--position--4----------- 4--)-------------- >< 
+-,--redraw-+ 


The setPos method sets the position of the scroll box for the associated scroll bar. 


Arguments: 


The arguments are: 
position 
The position to which the scroll box is to be moved. 


redraw 


If you specify 1 or Y, the scroll bar is redrawn using the new position. Otherwise, the new 
position is set, but the scroll bar display is not updated. The default value is 1. 
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Return value: 


Setting the position was successful. 


For all other cases. 


18.4. Position 


>>-a9CrollBar Pösition Ann аы == acca >< 


The Position method retrieves the position of the scroll box in the associated scroll bar. 


Return value: 


The position of the scroll box. 


18.5. DeterminePosition 


»»-aScrollBar^DeterminePosition(--posdata----------------------- ? 
»-—------------------------------------4-- )------------------- >< 
+-,--+------------ +--+------------- +-+ 


+-singleStep-+ +-,--pageStep-+ 


The DeterminePosition method determines the new position of the scroll box based on the position sent 
with the scroll bar notification messages. 


Arguments: 


The arguments are: 


posdata 


The position sent with the scroll bar notification messages. 


singleStep 


The value by which the scroll box position is increased or decreased when the user performs a 
single-step event like using the Down or Up arrow keys or clicking on the arrow buttons of the 
scroll bar. 
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pageStep 


The value by which the scroll box position is increased or decreased when the user performs a 
page-step event like using the PgDn or PgUp arrow keys or clicking on an area in the scroll bar 
that is not occupied by the scroll box or the arrow buttons. 


Return value: 
The resulting position based on posdata and the current position. 
Note: The position of a scroll bar cannot be modified directly by a user. The Object Rexx program 
must react to the notification that is the result of the user interaction and set the resulting position of 


the scroll box using setPos. Use the DeterminePosition method to determine the resulting position 
within your notification handler for the scroll bar notification messages. 


602 ooRexx OODialog Reference Version 4.0.0 


Chapter 19. ListControl Class 


A list view control is a window that displays a collection of items, with each item consisting of an icon 
and a label. It provides several ways of arranging and displaying items. Refer to OODLIST.REX in the 
OODIALOG\SAMPLES directory for an example. 


Use the GetListControl method (see page GetListControl) to retrieve an object of the ListControl class. 


Notes 


The ListControl class is the ooDialog interface to the Windows List-View control. This should not 
be confused with the Windows List Box control. The ooDialog ListBox class provides the interface 
to the Windows List Box control. In general, the List- View control is more powerful than the List 
Box control. 


List-View Extended Styles: The List-View control has been updated by Microsoft to include a 
number of extended styles. These styles are similar to the styles that can be used to create a 
ListControl, (see the AddListControl method,) like the NOHEADER or SINGLESEL styles. However, the 
way that they are added or removed from the ListControl is different. For instance, the extended 
styles can not be added to a ListControl at the time of creation. They can only be added after the 
underlying Windows control has been created. For all practical purposes this means in the 
InitDialog method, or at some point in the life cycle of the dialog after that. 


Some of the extended styles are only available on later versions of the Windows OS. As an example, 
the LABELTIP and SIMPLESELECT styles are only available on Windows XP. The documentation on 
the extended styles will note any requirements for each style. To work with the extended List- View 
styles, use the AddExtendedStyle, the RemoveExtendedStyle, or the ReplaceExtendedStyle 
methods. 


Note: There are a number of nuances to the behavior of the different extended styles on the 
different versions of Windows, far too many to try and detail in this documentation. The behavior 
documented here is the general behavior on Windows XP with service pack 2. 


If there is a need for detailed information concerning the subtle differences in behavior on 
earlier versions of Windows, the programmer should consult the Windows documentation. 


Requires: 
The ListControl class requires the class definition file oodwin32.cls: 
::requires "oodwin32.cls" 

Methods: 


Instances of the ListControl class implement the methods listed in the ListControl Instance Methods 
table. 


Table 19-1. ListControl Instance Methods 














Method... ..оп page 
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Add Add 

addRow addRow 
AddExtendedStyle AddExtendedStyle 
AddStyle AddStyle 
AlignLeft AlignLeft 
AlignTop AlignTop 
Arrange Arrange 
BkColor BkColor 
BkColor= BkColor= 

Check Check 

CheckAll CheckAll 
ColumnInfo ColumnInfo 
Column Width ColumnWidth 
Delete Delete 

DeleteAll DeleteAll 
DeleteColumn DeleteColumn 
Deselect Deselect 
DropHighlighted DropHighlighted 
Edit Edit 

EndEdit EndEdit 

Ensure Visible Ensure Visible 
Find Find 
FindNearestX Y FindNearestX Y 
FindPartial FindPartial 
FirstVisible FirstVisible 
Focus Focus 

Focused Focused 
GetCheck GetCheck 
getColumnCount getColumnCount 
getColumnOrder getColumnOrder 
GetExtendedStyle GetExtendedStyle 
GetExtendedStyleRaw GetExtendedStyleRaw 
GetHoverTime GetHoverTime 
getImageList getImageList 
insert insert 
InsertColumn InsertColumn 
IsChecked IsChecked 
ItemInfo ItemInfo 
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ItemPos ItemPos 
ItemState ItemState 
ItemText ItemText 

Items Items 
ItemsPerPage ItemsPerPage 
Last Last 
LastSelected LastSelected 
modify modify 
ModifyColumn ModifyColumn 
Next Next 

NextLeft NextLeft 
NextRight NextRight 
NextSelected NextSelected 
Prepare4nItems Prepare4nItems 
Previous Previous 
PreviousSelected PreviousSelected 
RedrawItems RedrawItems 





Removelmages Deprecated 


Removelmages Deprecated 





RemoveExtendedStyle 


RemoveExtendedStyle 





RemoveStyle 


RemoveStyle 





RemoveSmallImages Deprecated 


RemoveSmallImages Deprecated 
































ReplaceExtendedStyle ReplaceExtendedStyle 
ReplaceStyle ReplaceStyle 
RestoreEditClass RestoreEditClass 
Scroll Scroll 

Select Select 

Selected Selected 
SelectedItems SelectedItems 
SetColumn Width SetColumnWidth 
SetHoverTime SetHoverTime 
setImageList setImageList 





SetImages Deprecated 


SetImages Deprecated 














setColumnOrder setColumnOrder 
SetItemPos SetItemPos 
SetItemState SetItemState 
setItemText setItemText 





SetSmallImages Deprecated 


SetSmallImages Deprecated 








SmallSpacing 





SmallSpacing 
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SnapToGrid SnapToGrid 
Spacing Spacing 
StringWidth String Width 
SubclassEdit SubclassEdit 
TextBkColor TextBkColor 
TextBkColor= TextBkColor= 
TextColor TextColor 
TextColor= TextColor= 
Uncheck Uncheck 
UncheckAll UncheckAll 
Update Update 
UpdateItem UpdatelItem 





19.1. View Styles 


List view controls can display their contents in different 


views. The current view is specified by the 
window style of the control. Additional window styles define the alignment of the items and the 


functionality of the list view control. The different views are: 


Icon view 


Each item appears as a full-sized icon with a label below it. The user can drag the items to any 


location in the list view. 


Small-icon view 


Each item appears as a small icon with a label to the left of it. The user can drag the items to any 


location. 


List view 


Each item appears as a small icon with a label to the left of it. The user cannot drag the items. 


Report view 


Each item appears on a separate line with information arranged in columns. The leftmost column 
contains the small icon and the label. АП following columns contain subitems as specified by the 


application. 


19.2. Methods of the ListControl Class 


The following sections describe the individual methods. 
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19.2.1. ReplaceStyle 


+------------------- + 
ү 
»»-aListControl^ReplaceStyle(--oldStyle--,--"----4-ICON----------4-4--"--)-»« 

*-SMALLICON----- * 
*T-LISI---------- * 
*-REPORT-------- * 
*-ALIGNLEFT----- * 
*-ALIGNTOUP------ * 
*-AUTOARRANGE----* 
*-ASCENDING----- * 
*-DESCENDING----* 
+=ЕрІТ-========= + 
*-HSCROLL------- * 
*-VSCROLL------- + 
*-NOSCROLL------ * 
*-NOHEADER------ * 
+-NOSORTHEADER--+ 
*-NOWRAP-------- * 
*-SINGLESEL----- * 


+-SHOWSELALWAYS-+ 
+-SHAREIMAGES---+ 


+-GROUP--------- + 
*-HIDDEN-------- * 
*-NOTAB--------- * 
*-NOBORDER------ + 


The ReplaceStyle method removes a window style of а list view control and sets new styles. 


Arguments: 


The arguments are: 


oldStyle 


The window style to be removed. 


newStyle 


The new window styles to be set, which is one or more of the styles listed in the syntax 
diagram, separated by blanks. For an explanation of the different styles, refer to 
AddListControl. 


Return value: 


О if this method fails. 


Example: 


The following example comes from a program where the user can switch between the different view 
styles in a list-view. The list-view is assigned an image list for both the small and normal icons. 
Radio buttons for the different views are connected to methods. When the user clicks one of the 
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radio buttons, the method for that radio button uses replaceStyle() to remove all of the other view 
styles and add the specified style. 


::method initDialog 
expose list 


self~getRadioControl (IDC_RB_ICON) ~check 

self^connectButtonNotify (IDC RB, REPORT, "CLICKED", onReport) 
self^connectButtonNotify(IDC RB LIST, "CLICKED", onList) 
self^connectButtonNotify (IDC ВВ ICON, "CLICKED", onIcon) 
self^connectButtonNotify (10С ВВ SMALL, ICON, "CLICKED", onSmalllcon) 


list = self^getListControl(IDC LV. VIEWS) 


flags = .Image~toID(ILC_COLOR24) 
imageList = .ImageList^create(.Size^new(16), flags, 7, 0) 


imageList~add(.Image~ getImage ("iconList_16.bmp") ) 
list^setImageList(imagelist, .Image~toID(LVSIL_SMALL) ) 


imageList = .ImageList^create(.Size^new(32), flags, 7, 0) 


imageList~add(.Image~ getImage ("iconList_32. bmp") ) 
list^setImageList(imagelist, .Image~toID(LVSIL_NORMAL) ) 


self~populateList (list) 


::method onReport 
expose list 
list^replaceStyle("LIST ICON SMALLICON", "REPORT") 


::method onList 
expose list 
list^replaceStyle("REPORT ICON SMALLICON", "LIST") 


::method onIcon 

expose list 

list^replaceStyle("LIST REPORT SMALLICON", "ICON") 
::method onSmalllcon 

expose list 


list^replaceStyle("LIST ICON REPORT", "SMALLICON") 


::method populateList private 
use strict arg list 


list^InsertColumnEx(0, "Title", 150) 
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19.2.2. AddStyle 
+------------------- + 
ү 
»»-aListControl^AddStyle(--"----4-ICON---------- +-+--"--)------ >< 
*-SMALLICON----- + 
+-LIST---------- + 
*-REPORT-------- * 
*-ALIGNLEFT----- + 
*-ALIGNTOP------ + 
+-AUTOARRANGE---+ 
*-ASCENDING----- + 
+-DESCENDING----+ 
+-EDIT---------- + 
+-HSCROLL------- + 
*-VSCROLL------- + 
+-NOSCROLL------ + 
*-NOHEADER------ + 
+-NOSORTHEADER--+ 
*-NOWRAP-------- * 
*-SINGLESEL----- + 


+-SHOWSELALWAYS-+ 
+-SHAREIMAGES---+ 


+-GROUP--------- + 
+-HIDDEN-------- + 
*-NOTAB--------- * 
*-NOBORDER------ + 


The AddStyle method adds new window styles to a list view control. 


Arguments: 


The only argument is: 


style 


The window styles to be added, which is one or more of the styles listed in the syntax diagram, 
separated by blanks. For an explanation of the different styles, refer to AddListControl. 


Return value: 


О if this method fails. 


19.2.3. RemoveStyle 


+------------------- + 
ү 
>>-aListControl~RemoveStyle(--"----+-ICON---------- +-+--"--)--->< 
*-SMALLICON----- + 
+-LIST---------- + 
+-REPORT-------- + 
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*-ALIGNLEFT----- + 
*-ALIGNTOP------ + 
+-AUTOARRANGE---+ 
*-ASCENDING----- + 
+-DESCENDING----+ 
+-EDIT---------- + 
+-HSCROLL------- + 
*-VSCROLL------- + 
*-NOSCROLL------ + 
*-NOHEADER------ + 
+-NOSORTHEADER--+ 
*-NOWRAP-------- * 
*-SINGLESEL----- + 


+-SHOWSELALWAYS-+ 
+-SHAREIMAGES---+ 


+-GROUP--------- + 
*-HIDDEN-------- * 
*-NOTAB--------- * 
*-NOBORDER------ + 


The RemoveStyle method removes one or more window styles of a list view control. 


Arguments: 


The only argument is: 


style 


The window styles to be removed, which is one or more of the styles listed in the syntax 
diagram, separated by blanks. For an explanation of the different styles, refer to 
AddListControl. 


Return value: 


О if this method fails. 


19.2.4. AddExtendedStyle 


4-------------------- * 
V | 
»»-aListControl^AddExtendedStyle(--"---4*-BORDERSELECT----- g--1czI)------——---- >< 
+-СНЕСКВОХЕ5------- + 
*-DOUBLEBUFFER----- * 
*-ELATSB----------- * 
*-FULLROWSELECT-----* 
*-GRIDLINES-------- * 
+-HEADERDRAGDROP---+ 
*-INFÜTIP---------- * 
*-LABELTIP--------- * 


*t-MULTIWORKAREAS----* 
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+-OQNECLICKACTIVATE-+ 


*-REGIONAL--------- * 
*-SIMPLESELECT----- * 
+-SUBITEMIMAGES----+ 
*-TRACKSELECT------ * 


+-TWOCLICKACTIVATE-+ 
+-UNDERLINECOLD----+ 
*-UNDERLINEHOT----- + 


The AddExtendedStyle method adds опе or more of the extended List-View styles to a ListControl. 
These styles can not be added until the underlying Windows List-View control has been created. They 
can be added in the InitDialog method or any time thereafter. 


Arguments: 


The only argument is: 


style 


The extended styles to be added. This argument is a list containing one or more of the 
following style keywords, separated by blanks. Invalid words in the list are ignored. If there are 
no valid keywords at all in the list, then an error is returned. 


BORDERSELECT 


When an item is selected the border color of the item changes rather than the item being 
highlighted. 


CHECKBOXES 


Check boxes are visible and functional in all list view modes except tile mode. 


DOUBLEBUFFER 


Windows XP or later only. The list-view control is painted using double buffering. This 
reduces flicker. 


FLATSB 


Enables flat scroll bars. 


FULLROWSELECT 


Report view only. When a row is selected, the whole row is highlighted rather than just 
the first column. 


GRIDLINES 


Report view only. Gridlines are drawn around all items and sub-items. This gives a 
spreadsheet-like appearance to the list view control. 


HEADERDRAGDROP 


Report view only. The user can drag and drop the headers to rearrange the columns. 
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INFOTIP 
With this style a notification is sent to the parent window before displaying an item’s 
tooltip. (The current version of ooDialog can not take advantage of this style. It is planned 
for a future enhancement.) 

LABELTIP 
Windows XP or later only. In any list view mode, if an item’s label is only partially 
visible, the complete label will be displayed in a fashion similar to a tool tip. 

MULTIWORKAREAS 
The current version of ooDialog can not take advantage of this style. It is planned for a 
future enhancement. 

ONECLICKACTIVATE 


Enables the list-view control to send an item activate notification when the user clicks one 
time on an item. It also enables hot tracking in the list-view control. Both the underline 
cold and the underline hot styles need either one click activate or two click activate styles 
to be enabled. 


REGIONAL 


Icon view only. Sets the window region to only include an item's icon and text. 


SIMPLESELECT 


Windows XP and later only. Icon view only. Moves the state image to the top right of the 
icon image. If the user changes the state using the space bar, all the selected items cycle, 
not just the item with the focus. 


SUBITEMIMAGES 


Report view only. Allows images to be displayed for subitems. 


TRACKSELECT 


Enables hot track selection. The user can select an item by leaving the mouse over an item 
for a certain period of time, the "hover" time. This period of time can be changed from the 
default by using the SetHoverTime method. 


TWOCLICKACTIVATE 


Enables the list-view control to send an item activate notification when the user clicks on 
an item after it has been selected. When the user clicks on an item it will be selected. At 
that point, if the user clicks on the item a second time, the item will be activated. Note that 
this is different from double-clicking to activate. Any amount of time can pass between 
the click that selects the item and the click that activates the item. (Provided the item 
remains selected of course.) 


It also works with track select. If track select is enabled, the user can select an item by 
pausing the mouse over the item. At that point, if the user then clicks on the item it will be 
activated. 


612 ooRexx OODialog Reference Version 4.0.0 


Chapter 19. ListControl Class 


UNDERLINECOLD 


Underlining gives the user a visual clue that a single click on an item will activate it. 
Underlining requires either ONECLICKACTIVATE or TWOCLICKACTIVE to also be enabled. An 
item becomes hot when the mouse is over it. Underline cold underlines all the cold items 
when a single click will activate them. When one click activate is enabled, this would then 
be all items. When two click activate is enabled this would then be only those items that 
were selected. 


UNDERLINEHOT 


The underline hot style is similar to the underline cold style. See that style above for the 
explanation of some of the terms. With underline hot, the item is underlined when the 
mouse is over it, if one click will activate the item. 


Return value: 


The return values are: 


0 
Success. 
-1 
An (internal) problem with the control’s window handle. 
-3 
The style argument did not contain any of the extended style keywords. 
Example: 


The following example shows how to initially add the extended styles to a list view control. This is 
done in the InitDialog method, which executes after the underlying Windows dialog has been 
created, but before it is displayed on the screen. This is the earliest point in time that the extended 
style methods can be used. The list view is in the report view and will have check boxes and grid 
lines. The user will be able to use drag and drop to rearrange the columns. When a row is selected, 
the full row will be highlighted rather than just the first column. 


::method initDialog 
expose listView 


listView = self~getListControl (IDC_LIST) 
if listView == .nil then return 


listView~ addExtendedStyle ("CHECKBOXES GRIDLINES FULLROWSELECT HEADERDRAGDROP" ) 
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19.2.5. RemoveExtendedStyle 


4-------------------- + 
ү 
>>-aListControl~RemoveExtendedStyle (--"----+-BORDERSELECT----— +--"--)------- >< 
+-CHECKBOXES------- + 
+-DOUBLEBUFFER----- + 
*-ELATSB--—-------- * 
*-FULLROWSELECT-----* 
*-GRIDLINES-------- + 
+-HEADERDRAGDROP---+ 
+-INFOTIP---------= + 
+-LABELTIP--------- + 


+-MULTIWORKAREAS---+ 
+-OQNECLICKACTIVATE-+ 


+-REGIONAL--------- + 
*-SIMPLESELECT----- + 
+-SUBITEMIMAGES----+ 
*-TRACKSELECT------ + 


+-TWOCLICKACTIVATE-+ 
+-UNDERLINECOLD----+ 
T-UNDERLINEHOT----- * 





The RemoveExtendedStyle method removes one or more extended styles of a List-View control. 


Arguments: 


The only argument is: 


style 


The extended style(s) to be removed. This is one or more of the styles listed in the syntax 
diagram, separated by blanks. For an explanation of the different styles, refer to the 
AddExtendedStyle method. 


Return value: 


The return values are: 


0 

Success. 
-1 

An (internal) problem with the control’s window handle. 
-3 


The style argument did not contain any of the extended style keywords. 
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Example: 
The following example removes the check box style from the list view. 


listView = self~getListControl (IDC_LIST) 
if listView == .nil then return 


listView~ removeExtendedStyle ("CHECKBOXES") 


19.2.6. ReplaceExtendedStyle 


4-------------------- + 
ү | 
>>-aListControl~ReplaceExtendedStyle(-oldStyle-- , --"---+-BORDERSELECT-----+--"-)->< 
+-СНЕСКВОХЕ5------- + 
*-DOUBLEBUFFER----- * 
*T-PEATSB---—------—- + 
*-FULLROWSELECT-----* 
*-GRIDLINES-------- + 
+-HEADERDRAGDROP---+ 
*-INEÜTIP---------- + 
*T-LABELTIP--------- + 


+-MULTIWORKAREAS---+ 
+-OQNECLICKACTIVATE-+ 


*-REGIONAL--------- + 
*-SIMPLESELECT----- + 
+-SUBITEMIMAGES----+ 
*-TRACKSELECT------ + 


+-TWOCLICKACTIVATE-+ 
+-UNDERLINECOLD----+ 
*-UNDERLINEHOT----- * 


The ReplaceExtendedStyle method removes some of the List- View control’s extended styles and adds 
new extended styles. This is the equivalent of first using the RenoveExtendeStyle method and then using 
the AddExtendedStyle method. 


Arguments: 


The arguments are: 


oldStyle 


The extended style(s) to be removed. This is one or more of the styles listed in the syntax 
diagram, separated by blanks. For an explanation of the different styles, refer to the 
AddExtendedStyle method. 

newStyle 


The extended style(s) to be added. Again, this is one or more of the styles listed in the syntax 
diagram, separated by blanks. See the AddExtendedStyle method for the style descriptions. 
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Return value: 


The return values are: 


0 
Success. 
-1 
An (internal) problem with the control’s window handle. 
-3 
One, or both, of the style arguments had none of the extended style keywords. 
Example: 


The following example removes the cold and hot underlining and adds check boxes to the list view. 


listView = self~getListControl (IDC_LIST) 
if listView == .nil then return 


removeStyle = "UNDERLINECOLD UNDERLINEHOT" 
addStyle = "CHECKBOXES" 


listView^replaceExtendedStyle(removeStyle, addStyle) 


19.2.7. GetExtendedStyle 


>2-аГав Сон го! GetExtendedStyle-------—---—-————---ce-eeeoeeo eee >< 


The GetExtendedStyle method returns Ше extended styles of a ListControl. The styles are returned as a 
string of blank delimited style keywords. These are the same keywords as those used to set the styles. 


Arguments: 


This method takes no arguments. 


Return value: 


The returned string can contain one or more of the following style keywords. See the 
AddExtendedStyle method for the style descriptions: 


BORDERSELECT 
CHECKBOXES 
DOUBLEBUFFER 
FLATSB 
FULLROWSELECT 
GRIDLINES 
HEADERDRAGDROP 
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* INFOTIP 

* LABELTIP 

* MULTIWORKAREAS 
* ONECLICKACTIVATE 
* REGIONAL 

* SIMPLESELECT 

* SUBITEMIMAGES 

* TRACKSELECT 

* TWOCLICKACTIVATE 
* UNDERLINECOLD 

* UNDERLINEHOT 


Example: 


The following example comes from a fictious application where the user can elect to use the track 
select style, or not. With this style, an item can be selected by pausing the mouse over it for a period 
of time specified by the hover time. The application also allows the user to increase or decrease the 
hover time. In this example when the methods to increment or decrement the hover time are 
invoked, the application first checks to see if the list view control has the track select style. Then the 
change is only made if the list view control does have the style. 


::method initDialog 
expose listView 


listView = self^getListControl(IDC. LIST) 
if listView -- .nil then return 


listView^addExtendedStyle("CHECKBOXES FULLROWSELECT TRACKSELECT") 


::method onCheckboxClick 
expose listView 


chkBox = self^getCheckControl(IDC, CHECK, USETRACKSELECT) 
if chkBox^ checked then 
listView^addExtendedStyle("TRACKSELECT") 
else 
listView^removeExtendedStyle("TRACKSELECT") 


::method onDecrement 
expose listView 


styles - listView^getExtendedStyle 
if styles*wordpos("TRACKSELECT") == 0 then return 
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time = listView^getHoverTime - 100 
if time > 0 then listView~ setHoverTime (time) 


::method onIncrement 
expose listView 


styles = listView^getExtendedStyle 
if styles*wordpos("TRACKSELECT") == 0 then return 


-- Let the user increase the hover time to any length they want. 
listView^setHoverTime(list^getHoverTime + 100) 


19.2.8. GetExtendedStyleRaw 


2»-aListControl GetExtendedStyleRaw---------—-------------— eee eee >< 


The GetExtendedStyleRaw method returns the extended styles of a ListControl as the numeric value of 
the extended style flags. This method is provided for programmers familiar with the Windows API who 
may wish to know, or to work with, the actual value of the flags. 


Arguments: 


This method takes no arguments. 


Return value: 


The returned value is the numeric value of the extended style flags currently in effect for the 
list-view control. 


Example: 


The following example is the same example as the GetExtendedStyle example. It simply replaces 
the GetExtendedStyle invocation with a GetExtendedStyleRaw invocation. 


::method initDialog 
expose listView 


listView = self^getListControl(IDC, LIST) 
if listView -- .nil then return 


listView^addExtendedStyle("CHECKBOXES FULLROWSELECT TRACKSELECT") 


::method onCheckboxClick 
expose listView 


chkBox = self^getCheckControl(IDC, CHECK, USETRACKSELECT) 

if chkBox^checked then 
listView^addExtendedStyle("TRACKSELECT") 

else 
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listView^removeExtendedStyle("TRACKSELECT") 


::method onDecrement 
expose listView 


if .DlgUtil^and(listView^getExtendedStyleRaw, "Ox00000008") == 0 then return 


time - listView^getHoverTime - 100 
if time > O then listView^setHoverTime(time) 


::method onIncrement 
expose listView 


if .DlgUtil^and(listView^getExtendedStyleRaw, "Ox00000008") -- O then return 


-- Let the user increase the hover time to any length they want. 
listView^setHoverTime(list^getHoverTime + 100) 


19.2.9. GetHoverTime 


>>-аГав Сопъто! "СебНотет пе--------------<---------<- >< 


This method retrieves the current hover time. The hover time is expressed as milliseconds. The hover 
time only affects list view controls that have the track select, one click activate, or two click activate 
extended list view styles. See the AddExtendedStyle for a description of these styles. 


Arguments: 


This method takes no arguments 


Return value: 


The hover time. A value of -1 indicates the hover time is the system default hover time. 


Example: 


The following example comes from a program where the one click activate and track select styles 
are enabled. Orignally the hover time is set to .4 seconds. However the application allows the users 
to increase or decrease this time to match their preference. A menu item (or a button could be used) 
is connected to the onIncrement and onDecrement methods. When either of the methods is invoked, 
the current hover time is examined and then either incremented or decremented by .1 of a second. 


::method initDilaog 
expose list 


list = self^getListControl(IDC. LIST) 
list^addExtendedStyle("ONECLICKACTIVATE TRACKSELECT FULLROWSELECT") 
list^setHoverTime (400) 
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::method onDecrement 
expose list 


time = list^getHoverTime - 100 
if time > O then list^setHoverTime(time) 


::method onIncrement 
expose list 


-- Let the user increase the hover time to any length they want. 
list^setHoverTime(list^getHoverTime + 100) 


19.2.10. SetHoverTime 


»»-aListControl^SetHoverTime(--4------ 4--)--------------------- >< 


This method is used to change the hover time. The hover time only affects list view controls that have the 
track select, one click activate, or two click activate extended list view styles. See the AddExtendedStyle 
for a description of these styles. 


Arguments: 


The only optional argument is: 


time 
Specify the hover time in milliseconds. If this argument is omitted, the hover time is set to the 


system default. A negative number will also set the hover time back to the system defualt. 


Return value: 


The previous hover time. A value of -1 indicates the previous hover time was the system default. 


Example: 


The following example adds the one click activate, the track select, and the full row select extended 
list view styles to a ListControl. The hover time is set to .4 seconds. If the user pauses his mouse 
over a row in the list view for .4 of a second the row is automatically selectd. 


::method initDilaog 
list = self~getListControl (IDC_LIST) 
list^addExtendedStyle("ONECLICKACTIVATE FULLROWSELECT TRACKSELECT") 


oldTime = list^setHoverTime(400) 
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19.2.11. Check 


»»-aListControl^Check(--index--)-------------------------------------------- >< 


The Check method sets the check mark for a list view item. This method is only valid for list view 
controls that have the check boxes extended style. (See the AddExtendedStyle method for a description 
of the check boxes extended style.) 


Arguments: 


The only argument is: 


index 


The index of the item for which to set the check mark. 


Return value: 


The return values are: 


0 
Success. 
-1 
An (internal) problem with the control’s window handle. 
-2 
The list view control does not have the check boxes extended style. 
-3 
The index is invalid. 
Example: 


The following example is from a mailing list application. The user selects which entries to include 
in any mailing. АП items in a list view that have their check boxes checked are included in the 
mailing. The application has a feature that allows the user to automatically select all items with a 
specified zip code. 


::method onUseZip 


text = self^getEditControl(IDC EDIT ZIPCODE)^getText 
if self^validateZip(text) then do 
list = self^getListControl(IDC LIST) 
do i = 0 to addresses" items - 1 
infoTable = address[i + 1] 
if infoTable[’zip’] == text then list^check(i) 
end 
end 
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19.2.12. Uncheck 


»»-aListControl^Uncheck(--index--)------------------------------------------ >< 


The Uncheck method removes the check mark for a list view item. This method is only valid for list view 
controls that have the check boxes extended style. (See the AddExtendedStyle method for a description 
of the check boxes extended style.) 


Arguments: 


The only argument is: 


index 


The index of the item where the check box check is to be removed. 


Return value: 


The return values are: 


0 
Success. 
-1 
An (internal) problem with the control’s window handle. 
-2 
The list view control does not have the check boxes extended style. 
-3 
The index is invalid. 
Example: 


The following example is from a doctor's office custom accounting application. A list box is filled 
with information for every patient. One button in the application checks every patient with an 
outstanding balance, they will be mailed a statement for that balance. The doctor does not believe in 
sending billing statements to patients that have a very low balance. However what a "low" balance 
is depends on how he is feeling at statement time. Therefore the application allows the office 
manager to dynamically remove some patients from the statement list. 


::method onDeferBilling 
expose billingList 


text - self^getEditControl(IDC, EDIT. MINAMOUNT) ^getText 
minimun = self^decimalNumber (text) 


if minimum > 0 then do i = 0 to billingList^items 
if billingList^isChecked(i) then do 


-- Column 6 in the list is the patient's current balance. 
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owes = billingList~itemText(i, 6) 
if self^decimalNumber(owes) <= minimum then billingList^uncheck(i) 


end 
end 


19.2.13. CheckAll 


22-aListControl" Снеска  1------------- -<<---------- --<-- 


The СһескА11 method sets Ше check mark for every list view item. This method is only valid for list 
view controls that have the check boxes extended style. (See the AddExtendedStyle method for a 
description of the check boxes extended style.) 


Arguments: 
This method takes no arguments. 


Return value: 


The return values are: 


0 
Success. 
-1 
An (internal) problem with the control’s window handle. 
-2 
The list view control does not have the check boxes extended style. 
Example: 


The following example is from a program that has a push button that allows the user to check all the 
check boxes: 


::method onCheckAll 


list = self^getListControl(IDC, LIST. REPUBLICANS) 
list^checkAll 


19.2.14. UncheckAII 


22-aListControl UncheckAl]--—------—————------——— шыны ыы aa uec eric 


The Uncheck411 method clears the check mark for every list view item. This method is only valid for list 
view controls that have the check boxes extended style. (See the AddExtendedStyle method for a 
description of the check boxes extended style.) 
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Arguments: 


This method takes no arguments. 


Return value: 


The return values are: 


0 
Success. 
-1 
An (internal) problem with the control’s window handle. 
-2 
The list view control does not have the check boxes extended style. 
Example: 


The following example is from a program that has a push button that allows the user to remove the 
check mark from all the check boxes: 


::method onUncheckAll 


list = self~getListControl (IDC_LIST_REPUBLICANS) 
list^uncheckAll 


19.2.15. GetCheck 


»»-aListControl^GetCheck(--index--)----------------------------------------- >< 


The GetCheck method determines if the item at the specified list index has a checked check box. This 
method will return a code indicating that the list view control does not have the check boxes extended 
style, if appropriate. (See the AddExtendedStyle method for a description of the check boxes extended 
style.) 


Arguments: 


The only argument is: 


index 


The index of the item to query. 
Return value: 


The return values are: 


The item has a check box that is checked. 
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0 
The item has a check box, and it is not checked. 
-1 
An (internal) problem with the control’s window handle. 
-2 
The list view control does not have the check boxes extended style. 
-3 
The index is invalid. 
Example: 


The following example could be used as a shortcut method to determine if a list view control 
currently has the check box extended style. 


list = self^getListControl(IDC LV DOCTORS) 
if list^getCheck(0) -- -2 then 
return  -- The list view does not currently have the check box style in effect 


do і = 0 to list~items - 1 


end 


19.2.16. IsChecked 


»»-aListControl^IsChecked(--index--)---------------------------------------- >< 


The IsChecked method determines if a check box for a list view item is checked or not. This method will 
always return true or false. It can be used if the list view control has or does not have the check boxes 
extended style. (See theAddExtendedStyle method for a description of the check boxes extended style.) 


Arguments: 


The only argument is: 


index 


The index of the item to query. 


Return value: 


The return values are: 


true 


The list view item has a check box and it is checked. 
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false 


There is no check mark for the list view item. Either the list view has check boxes and the 
check box is not checked, the index is out of range or not valid, or the list view does not have 
the check box extended style. 


Example: 


The following example is from a doctor’s office custom accounting application. A list box is filled 
with information for every patient. After the office mananger has finished working with the 
accounts a mail merge is done to produce statements for all patients that are to receive statements 
for the month. For every patient item in the list view, if the item has a check mark, then that patient 
is mailed a statement. 


::method onCreateMailMerge 
expose patientList 


do 1 = 0 to patientList^ items 
if billingList~isChecked(i) then do 
self~addToMailMerge(billingList, i) 
end 
end 


19.2.17. InsertColumn 


+-0------ + 
»»-aListControl^InsertColumn(--4-------- dee berto 


»--,--Width--4--------------------- *--)--------------- >< 
| +-LEFT---+ | 
+- --!--+-СЕНТЕВ-+--"-+ 
+-RIGHT--+ 


The InsertColumn method sets the attributes of a report list view column. 


Arguments: 


The arguments are: 


column 


The number of the column. 0 is the first column and the default. 


text 


The text of the column heading. 
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width 
The width of the column, in pixels. 
align 
The alignment of the column heading and the subitem text within the column. It can be one of 
the following values: 
CENTER 
The text is centered. 
LEFT 
The text is left-aligned, which is the default. 


RIGHT 


The text is right-aligned. 


Return value: 


The number of the new column, or 0 if this method fails. 


Example: 


The following example adds three columns to a report list: 


::method InitReport 

curList = self~GetListControl (102) 

if curList \= .Nil then 

do 
curList~InsertColumn(0,"First Name" ,50) 
curList~InsertColumn(1,"Last Name" ,50) 
curList^InsertColumn(2,"Age",50) 

end 


19.2.18. DeleteColumn 


»»-aListControl^DeleteColumn(--column--)----------------------- >< 


The DeleteColumn method removes a column from a list view control. 


Arguments: 


The only argument is: 


column 


The number of the column to be deleted. The first column must be deleted last. 
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Return value: 


The column was deleted. 
You did not specify column. 


For all other cases. 


19.2.19. ModifyColumn 


>>-aListControl~ModifyColumn (--column-- ,--+------+-- ,--width----> 
*t-text-t 
»--—--------------------- 4--)---------------------------------- >< 
| *-LEFT---. | 
+-,„т-"--+-СЕКТЕВ-+--"-+ 
+-втант--+ 


The ModifyColumn method sets new attributes for a column of a list view control. 


Arguments: 


The arguments are: 
column 
The number of the column. 0 is the first column. 


text 


The text of the column heading. If you omit this argument, the heading is not changed. 


width 


The width of the column, in pixels. 


align 


The alignment of the column heading and the subitem text within the column. It can be one of 
the following values: 


CENTER 


The text is centered. 
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LEFT 


The text is left-aligned, which is the default. 


RIGHT 
The text is right-aligned. 


Return value: 


0 
The column was modified. 
-1 
You did not specify column. 
1 
For all other cases. 
Example: 


The following example changes the title, size, and alignment of the first column in a report list: 


::method ChangeColumn 
curList = self~GetListControl (102) 
curList~ModifyColumn(0,"New Title",100,"RIGHT") 


19.2.20. Columninfo 


»»-aListControl^ColumnInfo(--column--)------------------------- >< 


The ColumnInfo method retrieves the attributes of a column of a list view control. 


Arguments: 


The only argument is: 


column 


The number of the column of which the attributes are to be retrieved. 0 is the first column. 
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Return value: 


A compound variable that stores the attributes of the item. If attributes for a column are not 
available ог an error occurs, then the RetStem.!WIDTH variable will be set to 0. 


RetStem.!TEXT 


The heading of the column. 


RetStem.!COLUMN 


The column number. 


RetStem.!WIDTH 


The width of the column. 


RetStem.! ALIGN 


The alignment of the column: "LEFT", "RIGHT", or "CENTER". 


Example: 


The following example displays the column attributes in an information box when the column is 


clicked on: 


::method onColumnClick 
use arg id, column 


listView = self^getListContro1(100) 


info. = listView^columnInfo(column) 

msg = "Column Title : " info.!Text || .endOfLine || - 
"Column Number: " info.!Column || .endOfLine || - 
"Column Width : " info.!Width || .endOfLine || - 
"Alignment : " info.!Align 


call infoDialog msg 


19.2.21. ColumnWidth 


»»-aListControl^ColumnWidth(--column--)------------------------ >< 


The ColumnWidth method retrieves the width of a column in a report or list view. 


Arguments: 


The only argument is: 


column 


The number of the column of which the width is to be retrieved. 0 is the first column. 
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Return value: 


The column width, or -1 if you did not specify column, or О in all other cases. 


Example: 


The following example displays the column width in an information box when the column is 


clicked on: 


::method onColumnClick 


use arg id, column 
listView = self^getListContro1(102) 
call infoDialog listView^columnWidth(column) 


19.2.22. SetColumnWidth 


»»-aListControl^SetColumnWidth(--column--4---------- *--)------- >< 
+-,--width-+ 


The SetColumnWidth method sets the width of a column in a report or list view. 


Arguments: 


The arguments are: 


column 


The number of the column of which the width is to be set. 0 is the first column. 


width 


The width of the column, in pixels. If you omit this argument, the column is sized 


automatically. 


Return value: 


The column width was set. 


You did not specify column. 


For all other cases. 
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Example: 
The following example enlarges the selected column by 10: 


::method OnColumnClick 
use arg id, column 
curList = self~GetListControl (102) 
curList~SetColumnWidth (column, curList~ColumnWidth (column) +10) 


19.2.23. getColumnCount 


>>)==get ColumnCount ======шя< 5 SSS SSeS SSS Sasa SSS aS SSS шаны нен ыш шнын >< 


This method returns the number of columns in the list-view control when it is in report view. 


Arguments: 


There are no arguments. 


Return value: 


This method returns the number of colunms, or -1 on some error. An error is unlikely. 


Example: 
This method is straight forward to use: 


colCount = list^getColumnCount 


19.2.24. getColumnOrder 


>>>-pet Column Orders se Se Sas >< 


Retrieves the current column order of the list-view when in report view. The order of the columns can be 
changed programmatically by using the setColumnOrder() method. In XP and later there is also an 
extended style which lets the user rearrange the order of the columns. If the list-view control has not had 
the columns rearranged, then the column order will always be 0, 1, 2, ... of course. 


One practical use of this method would be in conjuction with the setColumnOrder() method. In an 
application where the user can rearrange the column order, the programmer could get the order when a 
dialog closes, save it, and then restore the order to the user’s preference when the application is restarted. 


Note that the list-view control does not have to have the HEADERDRAGDROP style for the get and set 
column order methods to work. That style is only needed to allow the user to rearrange the columns 
using drag and drop. The programmer can use setColumnOrder() to change the order of the columns 
whether or not the list-view has the HEADERDRAGDROP style, or not. 


Arguments: 


There are no arguments. 
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Return value: 


The possible return values are: 


an .Array object 


An array is returned with the index numbers of the columns. The number at the first position in 
the array is the column index of the left-most column. The number in the second position in the 
array is the index of the second left-most column, etc.. 

.nil 


.nilis returned for some unexpected error. This is unlikely. 


Example: 


This example prints out the column order when the dialog is first initialized, and then prints out the 
order when the dialog closes. 


list = self^getListContro1(100) 


columnNames = .array~of("Occupation", "Name", "Age", "Sex") 
list^addExtendedStyle("FULLROWSELECT GRIDLINES CHECKBOXES HEADERDRAGDROP" ) 


list~InsertColumn(0, columnNames [1], 95) 
list~InsertColumn(1, columnNames[2], 95) 
list^InsertColumn(2, columnNames[3], 95) 





list^InsertColumn(3, columnNames[4], 35) 


self~printColumnOrder 


::method close 


self~printColumnOrder 
return self^ok:super 


::method printColumnÜrder private 
expose list columnNames 


cols = list^getColumnÜrder 

say ’cols:’ cols 

say ’Column count: ? list” getColumnCount 
say ’Current order:’ 


if cols^isA(.array) then do c over cols 





-- Column indexes are zero-based 
с += 1 
say " " columnNames[c] 

епа 


/* Output might be, (assuming the user changed the order): 


cols: an Array 
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Column count: 4 
Current order: 
Occupation 
Name 
Age 
Sex 


cols: an Array 
Column count: 
Current order: 
Age 
Name 
Sex 
Occupation 


*/ 


19.2.25. setColumnOrder 


»»--setColumnÜrder(--order--)----------------------------------------- >< 


Changes the column order of a list-view control to some other order. Typically this method might be used 
along with the getColumnOrder() method to save and restore the user's column order. But, it can also be 
used to programmatically change the column order for any reason. 


Details: 


Raises syntax errors when incorrect arguments are detected. 


Arguments: 


The single required argument is: 


order 


An array containing the index numbers of the columns in their new order. The number at the 
first position in the array is the column index of the column that should be the left-most. The 
number at the second position in the array, and so on. 


The array has to contain the same number of items as the number of columns with no empty 
indexes. 


If non-valid column indexes are intermingled with valid column indexes, then the columns are 
re-ordered, but with no easily predictable pattern. If all the number are invalid column indexes, 
then the order of the columns remains unchanged. This behavior is the behavior of the 
underlying control, ooDialog has no control over it. 
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Return value: 


The possible return values are: 


. true 


The method succeeded. 


.false 


Some error occurred. This is unlikely. 


Example: 


In this example an application has two modes. One mode emphasizes the occupation of the people 
in a database, the other mode emphasizes the people. The order of the columns is occupation, name, 
... for the first mode and name, occupation, ... for the second mode. When the mode of the 
application changes, the order of the columns also changes. 


list = self~getListControl (100) 


columnNames = .array~of("Occupation", "Name", "Age", "Sex") 
list~addExtendedStyle("FULLROWSELECT GRIDLINES CHECKBOXES") 


list~InsertColumn(0, columnNames [1], 95) 
list~InsertColumn(1, columnNames[2], 95) 
list^InsertColumn(2, columnNames[3], 95) 





list^InsertColumn(3, columnNames[4], 35) 


::method toggleColumnOrder private 
expose list 


order = list^getColumnÜrder 
tmp = order[1] 
order[1] = order[2] 


order[2] = tmp 
list^setColumnOrder (order) 


19.2.26. StringWidth 


»»-aListControl^StringWidth(--text--)-------------------------- >< 


The String Width method determines the width of a specified string using the current font of the list view 
control. 
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Arguments: 


The only argument is: 


text 


The text string of which the width is to be determined. 


Return value: 


The string width, or -1 if you did not specify a text, or 0 in all other cases. 


19.2.27. insert 


>>--insert (--+------ +--,--+--------- +-- ,--text--+-------- +--)------------------ >< 
+-item-+ +-subitem-+ +-,-icon-+ 
The insert method inserts a new item into the list-view control, or inserts the text of a subitem. 


Remember that in a list-view, items and columns use a 0-Базед index. Subitems use а 1-based index. 


Arguments: 


The arguments are: 


item 
The index of the item to insert or the item whose subitem text is inserted. 
When this argument is omitted and subitem is omitted or 0, ooDialog uses the index of the last 
item added to the list-view control, plus 1, as the item index. If the argument is omitted and 


subitem is greater than 0, then the index of the last item added is used. If no items have yet 
been added, then 0 is used. 


subitem 


The subitem number. This argument is used to insert the text for a subitem of the item. In 
report view, the label (text) for the item is placed in column 0. The text for subitem 1 is placed 
in column 1, the text for subitem 2 is placed in column 2, and so on. If you omit this argument, 
or use 0, the the text argument is assigned as the label (text) of the item. If you use this 
argument and it is greater than 0, then the text argument is assigned as the text of that subitem. 
Note that when this argument is greater than 0, no new item is inserted into the list-view. 
Rather, the text of the subitem is inserted into an existing list-view item. 


text 
The text of the item, or of the subitem, depending on the subitem argument. 
icon 


The index of the icon within the image list for this item. Use the setImageList() method to 
assign an image list to the list-view control. With setImageList(), use the LVSIL SMALL 
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type to set the image list for the small icons and the LVSIL_NORMAL type for the normal size 
icon image list. 


The normal size icons are used for the icon view and the small icons are used for the list, 
report, and small-icon views. Note that there is only one index for each list-view item. This 
implies that the normal icon for an item must be at the same index in the normal image list as 
the small icon is at in the small icon image list. 


Use -1 or simply omit this argument to indicate there is no icon for the item being inserted. 
This argument is ignored completely if subitem is greater than 0. 


Return value: 


The index of the new item, or -1 in all other cases. 


Example: 
The following example inserts items in a list: 


::method initReport 
curList = self~getListControl (102) 
if curList \= .nil then 


do 
curList^insert(, ,"First") 
curList^insert(, ,"Second") 
curList^insert(, ,"Third") 
end 


19.2.28. modify 


>>--modify (--+------ aa a emm *--,--text---------- 4--)------------------ >< 
+-item-+ +-subitem-+ +-,-icon-+ 


The modify method modifies or sets the text for the item label, or the text for a subitem, for a list-view 
item. Optionally, it sets or modifies the icon index for a list-view item. 


Remember that in a list-view, items and columns use a 0-Базед index. Subitems use a 1-based index. 


Arguments: 


The arguments are: 


item 


The index of the item to be modified. If you omit this argument, the selected item is used. 


subitem 


This method works in a similar manner as the insert() method. The use of the subitem 
argument controls whether the text argument applies to the label of the item or the text of a 
subitem. When subitem is omitted or 0, then the label of the item is set to text. When subitem is 
greater than 0, then the text of that subitem is set to text. 
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text 
The new text for the item label, or the new text for the subitem of the item, depending on the 
value of subitem. 

icon 


The new index of the icon for the item within the image list assigned to the list-view. Image 
lists are assigned with the setImageList() method. When assigning the image list with 
setImageList(), use the LVSIL_NORMAL flag for the icon view icons and the 
LVSIL_SMALL flag for the list, report, and small-icon view icons. 


Use -1 or simply omit this argument to leave the icon index unchanged. If subitem is greater 
than 0, this argument is ignored. 


Return value: 


0 
The modification was successful. 
1 
For all other cases. 
Example: 


The following example modifies the icon for an item when it is activated. A method, onActivate, is 
connected to the ACTIVATE notification. When an item is activated it also gains the focus. The 
onActivate() method is invoked when an item is activated, and the example determines which item 
was activated by seeing which item has the focus. 


::method initDialog 
expose list 


list = self^getListControl(IDC LV, VIEWS) 
self^connectListNotify(IDC LV VIEWS, ? ACTIVATE’, "onActivate?) 


::method onActivate 
expose list 


focusedItem = list~ focused 
text = list~itemText (focusedItem) 


list^modify(focusedItem, , text, 2) 


19.2.29. setitemText 


>>--setItemText (--item--,--4----------- *--,--text--)--»« 
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The setItemText method changes the text of a label, or the text of a subitem, of a list view item. 


Remember that in a list-view, items and columns use a 0-Базед index. Subitems use a 1-based index. 


Arguments: 


The arguments are: 
item 
The index of the item. 


subitme 


This method works in a similar manner as the insert() method. The use of the subitem 
argument controls whether the text argument applies to the label of the item or the text of a 
subitem. When subitem is omitted or 0, then the label of the item is set to text. When subitem is 
greater than 0, then the text of that subitem is set to text. 


text 


The text for the item or a subitem, depending on the value of subitem. 


Return value: 


The change was successful. 


You did not specify item. 


For all other cases. 


19.2.30. SetltemState 


»»-aListControl^SetlItemState(--item--4------------------------------ +--)->< 

| +-==——---==-—==—_=-=—= + | 

| ү | | 

+-,--"----+-CUT--------- +-+--"-+ 
*-NOTCUT------ + 
+-DROP-------- + 
*-NOTDROP----- * 
*-FÜCUSED----- * 


+-NOTFOCUSED--+ 
+-SELECTED----+ 
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+-NOTSELECTED-+ 


The SetItemState method sets the state of a list view item. 


Arguments: 


The arguments are: 


item 
The number of the item. 


state 


The state of the item, which can be one or more of the following values, separated by blanks: 


CUT 


The item is marked for a cut-and-paste operation. 


NOTCUT 


The item cannot be used for a cut-and-paste operation. 


DROP 
The item is highlighted as a drag-and-drop target. 


NOTDROP 
The item is not highlighted as a drag-and-drop target. 


FOCUSED 


The item has the focus and is therefore surrounded by the standard focus rectangle. Only 
one item can have the focus. 


NOTFOCUSED 


The item does not have the focus. 


SELECTED 


The item is selected. Its appearance depends on whether it has the focus and on the 
system colors used for a selection. 


NOTSELECTED 


The item is not selected. 
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Return value: 


The state was set successfully. 


You did not specify item. 


For all other cases. 


19.2.31. add 


+------- + 
ү | 
»»--add(----4----- *--text--4-------- +--)------- >< 
+--,--+ +-,-icon-+ 


The add method adds a new item to a list-view, or defines the text for a subitem. It can be used to fill a 
list-view sequentially. 


Remember that in a list-view, items and columns use а 0-Базед index. Subitems use a 1-based index. 


The number of commas preceding the text argument determines whether a new item is added to the 
list-view or the text for a subitem is being defined. When there is no comma preceding text then a new 
item is added to the list-view. 


When 1 or more commas precede text, then no item is added to the list-view. Rather, the text for a 
subitem is defined. When 1 comma precedes text, then the text for subitem | is being defined. When 2 
commas precedes the text argument, then the text for subitem 2 is being defined, and so on. 


When an item is added, it is always added directly after the last item to be placed in the list-view. Or as 
item O if the list-view currently has no items. When the text of a subitem is being defined, then the text is 
defined for the subitem of last item placed in the list-view. 


Arguments: 


The arguments are: 


As explained above, this argument determines if an item is added to the list-view, or if the text 
of a subitem is defined. 


text 


The text for the item label, or the text for the subitem of a item, depending on whether an item 
is being added or the text for a subitem is being defined. 
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icon 


Specifies the index within the image list for the icon for this item. Image lists are assigned to a 
list-view by using the setImageList() method. With the setImageList() method, use the 
LVSIL NORMAL flag for the icon view icons and the LVSIL. SMALL flag for the list, report, 
and small-icon view icons. 


Use -1 or simply omit this arugment to indicate there is no icon for the item being added. This 
argument is ignored completely when the text for a subitem is being defined. 


Example: 


The following example adds three columns and two items to a report list control. To get the 
following result: 




















First Name Last Name Age 
Mike Miller 30 
Sue Thaxtor 29 





using the add() method you must specify something similar to the following: 


::method initDialog 


curlist - self^getListControl(IDC LIST, REP) 
if curList \= .nil then do 


imageList = .ImageList^create(.Size^new(16), .Image~toID(ILC_COLOR24), 9, 0) 
imageList^add(.Image^getImage("E:NVoodlistNoodlist.BMP")) 
list^setImageList(imagelist, .Image^toID(LVSIL SMALL)) 


curList~insertColumn(0,"First Name",50) 
curList~insertColumn(1,"Last Name",50) 
curList^insertColumn(2,"Age",50) 


-- 3 is the index in the image list for the icon for item O 
curList^add("Mike", 3) 

curList^add(,"Miller") 

curList^add(, ,"30") 


-- 0 is the index in the image list for the icon for item 1 
curList^^add("Sue", 0)^^add(,"Thaxton")^^add(, ,"29") 


end 


19.2.32. addRow 


>>--addRow (--+------+-- ,--icon-- ,----text-+--)----->< 


+-item-+ 
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The addRow method adds a new item to a list-view. This method is most useful when adding items that 
have subitems to the list-view. But, despite its name, it can be used to add any item, with or without 
subitems, to a list-view. 


Remember that in a list-view, items and columns use a 0-Базед index. Subitems use a 1-based index. 


Arguments: 


The arguments are: 


item 


The index of the item. If you omit this argument, the item is added immediately after the last 
item added or inserted in the list-view. That is, the index defaults to the index of the last item 
added plus 1. If there are no items in the list-view then the item is added at index 0. 


icon 


The index within the image list for the icon for this item. Image lists are assigned to a list-view 
by using the setImageList() method. With the setImageList() method, use the 

LVSIL NORMAL flag for the icon view icons and the LVSIL. SMALL flag for the list, report, 
and small-icon views icons. 


text 


Any number of text strings. The first text string is used for the label of the item. Successive 
strings are used for the text of subitems of the item. For example, the text of the second string 
is used for the text of subitem 1. The text of the third string is used for the text of subitem 2, 
and so on. If the first string is omitted, then the empty string is used for the item label. If other 
strings are omitted, than no text is set for the corresponding subitem. If you specify more text 
entries than there are columns, the extra entries are ignored. 


Return value: 


The index of the new item, or -1 in all other cases. 


Example: 


The following example adds three items to a report list with two columns: 


::method InitList 
curList - self^GetListControl(101) 
curList^addRow(, ,"Mike","Miller") 
curList^addRow(, ,"Sue","Muller") 
curList^addRow(, ,"Chris","Watson") 


19.2.33. Delete 


»»-aListControl^Delete(--item--)------------------------------- >< 


The Delete method removes an item from a list view control. 
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Arguments: 


The only argument is: 


item 


The number of the item. 


Return value: 


0 
The item was deleted. 
-1 
You did not specify item. 
1 
For all other cases. 
Example: 


The following example deletes the selected item in a list control: 


::method DeleteSelectedItem 
curList = self~GetListControl (102) 
curlist^Delete(curList^Selected) 


19.2.34. DeleteAll 


»»-aListControl^DeleteAll-------------------------------------- 


The DeleteAll method removes all items from a list view control. 


Return value: 


The items were deleted. 


No item was available. 
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For all other cases. 


19.2.35. Items 


s»-abistControl Тъешв------л-<-л-енян 59 SSSR е э шт >< 


The Items method retrieves the number of items in a list view control. 


Return value: 


The number of items. 


19.2.36. Last 
»2-aLlastControl Last -=A тя SSS acces >< 
The Last method retrieves the number of the last item in a list view control. 


Return value: 


The number of the last item. 


19.2.37. Prepare4nitems 
»»-aListControl^Prepare4nItems(--items--)---------------------- >< 
The Prepare4nItems method prepares a list view control for adding a large number of items. 


Arguments: 


The only argument is: 


items 


The number of the items to be added later. 


Return value: 


The list view control was prepared. 


ooRexx OODialog Reference Version 4.0.0 645 


Chapter 19. ListControl Class 


-1 


You did not specify items. 


19.2.38. Selecteditems 


2»-aListControl SelectedTtems---------—-—----—---------oneceooo >< 


The SelectedItems method determines the number of selected items in a list view control. 


Return value: 


The number of selected items. 


19.2.39. ItemInfo 


+-0------ + 
»»-aListControl^ItemInfo(--item--,--4-------- 4--)-------------- >< 
+-column-+ 


The ItemInfo method retrieves the attributes of a list view item. 


Arguments: 


The arguments are: 


item 


The number of the item. 


column 


The number of the column. If you omit this argument, 0 is assumed. 


Return value: 


A compound variable that stores the attributes of the item, or -1 in all other cases. The compound 
variable can be: 


RetStem.!TEXT 


The item text. 


RetStem.!IMAGE 


The index of the icon in the image list this for item. Image lists are assigned to list-views using 
the setImageList() method. 
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In report view, this index is only used for the icon for the first column. ooDialog does not yet 
support setting the icon index for the other columns in a report view. 


RetStem.!STATE 


One or more of the following values: 


CUT 


The item is marked for a cut-and-paste operation. 


DROPPED 
The item is highlighted as a drag-and-drop target. 


FOCUSED 


The item has the focus and is therefore surrounded by the standard focus rectangle. Only 
one item can have the focus. 


SELECTED 


The item is selected. Its appearance depends on whether it has the focus and on the 
system colors used for a selection. 


Example: 


The following example displays the item text, icon index, and the item state in a message box: 


::method displayItemInfo 


listView = self~getListControl (100) 
item = listView~selected 


if item == -1 then do 
msg = "No item selected." 
end 
else do 
itemInfo. = listView^itemInfo(item) 
msg = "Item Text : " itemInfo.!Text || .endOfLine || - 
"Image Index : " itemInfo.!Image || .endOfLine || - 
"Item State : " itemInfo.!State 
end 


call infoDialog msg 


19.2.40. ItemText 


»»-aListControl^ItemText(--item--,--4-------- 4--)-------------- >< 
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Arguments: 


The arguments are: 
item 

The number of the item. 
column 


The number of the column. If you omit this argument, 0 is assumed. 


Return value: 


The item or column text, or -1 if you did not specify item. 


19.2.41. ItemState 


»»-aListControl^ItemState(--item--)---------------------------- >< 


The ItemState method retrieves the state of a list view item. 


Arguments: 


The only argument is: 


item 


The number of the item. 


Return value: 


The state of the item, which can be one or more of the following values: 


CUT 


The item can be used in a cut-and-paste operation. 


DROPPED 
The item is highlighted as a drag-and-drop target. 


FOCUSED 


The item has the focus and is therefore surrounded by the standard focus rectangle. Only one 
item can have the focus. 
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SELECTED 


The item is selected. Its appearance depends on whether it has the focus and on the system 


colors used for a selection. 


19.2.42. Select 


>>-aListControl~Select (--item--)------------------------------- >< 


The Select method selects an item. 


Arguments: 


The only argument is: 


item 


The number of the item. 


Return value: 


The item was selected. 


You did not specify item. 


For all other cases. 


19.2.43. Deselect 
»»-aListControl^Deselect(--item--)----------------------------- >< 
The Deselect method deselects an item. 


Arguments: 


The only argument is: 


item 


The number of the item. 
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Return value: 


The item was selected. 


You did not specify item. 


For all other cases. 


19.2.44. Selected 


»»-aListControl^Selected--------------------------------------- >< 


The Selected method returns the number of the selected item. 


Return value: 


The number of the item selected last, or -1 in all other cases. 


19.2.45. LastSelected 


»»-aListControl^LastSelected----------------------------------- >< 


The LastSelected method returns the number of the item selected last. 


Return value: 


The number of the item selected last, or -1 in all other cases. 


19.2.46. Focused 


»»-aListControl^Focused---------------------------------------- >< 


The Focused method retrieves the number of the item that has currently the focus. 


Return value: 


The number of the item with the focus, or -1 in all other cases. 
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19.2.47. Focus 


»»-aListControl^Focus(--item--)-------------------------------- >< 


The Focus method assigns the focus to the specified item, which is then surrounded by the standard focus 
rectangle. Although more than one item can be selected, only one item can have the focus. 


Arguments: 


The only argument is: 


item 


The number of the item to receive the focus. 


Return value: 


The specified item received the focus. 
You did not specify item. 


For all other cases. 


19.2.48. DropHighlighted 


»»-aListControl^DropHighlighted-------------------------------- >< 


The DropHighlighted method retrieves the item that is highlighted as a drag-and-drop target. 


Return value: 


The number of the selected item, or -1 in all other cases. 


19.2.49. FirstVisible 


»»-aListControl^FirstVisible----------------------------------- >< 


The FirstVisible method retrieves the number of the first item visible in a list or report view. 
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Return value: 


The number of the first item visible, or O if the list view control is in icon or small-icon view. 


19.2.50. NextSelected 


»»-aListControl^NextSelected(--item--)------------------------- >< 


The NextSelected method retrieves the selected item that follows, or is to the right of, item. 


Arguments: 


The only argument is: 
item 
The number of the item at which the search is to start. The specified item itself is excluded 


from the search. 


Return value: 


The number of the selected item, or -1 in all other cases. 


19.2.51. PreviousSelected 


»»-aListControl^PreviousSelected(--item--)--------------------- >< 


The PreviousSelected method retrieves the selected item that precedes, or is to the left of, item. 


Arguments: 


The only argument is: 
item 
The number of the item at which the search is to start. The specified item itself is excluded 


from the search. 


Return value: 


The number of the selected item, or -1 in all other cases. 


19.2.52. Next 


>>-aListControl~Next (--item--)--------------------------------- >< 
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The Next method retrieves the item that follows, or is to the right of, item. 


Arguments: 


The only argument is: 


item 


The number of the item at which the search is to start. 


Return value: 


The number of the following item, or -1 in all other cases. 


19.2.53. Previous 


»»-aListControl^Previous(--item--)----------------------------- >< 


The Previous method retrieves the item that precedes, or is to the left of, item. 


Arguments: 


The only argument is: 


item 


The number of the item at which the search is to start. 


Return value: 


The number of the previous item, or -1 in all other cases. 


19.2.54. NextLeft 


»»-aListControl^NextLeft(--item--)----------------------------- >< 


The NextLeft method retrieves the item left to item. 


Arguments: 


The only argument is: 
item 


The number of the item at which the search is to start. The specified item itself is excluded 
from the search. 
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Return value: 


The number of the next item to the left, or -1 in all other cases. 


19.2.55. NextRight 
»»-aListControl^NextRight (--item--)---------------------------- >< 
The NextRight method retrieves the item right to item. 


Arguments: 


The only argument is: 
item 
The number of the item at which the search is to start. The specified item itself is excluded 


from the search. 


Return value: 


The number of the next item to the right, or -1 in all other cases. 


19.2.56. SmallSpacing 


»»-aListControl^SmallS8pacing----------------------------------- >< 


The SmallSpacing method determines the spacing between items in a small-icon list view control. 


Return value: 


The amount of spacing between the items. 
19.2.57. Spacing 
»»-aListControl^Spacing---------------------------------------- >< 


The Spacing method determines the spacing between items in an icon list view control. 


Return value: 


The amount of spacing between the items. 
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19.2.58. Redrawltems 


»»-aListControl^RedrawItems--t-------------------------- prec >< 
+-(--first--+--------- +--)-+ 
+-,--last-+ 


The RedrawItems method forces a list view control to redraw a range of items. 


Arguments: 


The arguments are: 


first 


The number of the first item to be redrawn. The default is 0. 


last 


The number of the last item to be redrawn. The default is O. 


Return value: 


The specified range of items was redrawn. 


For all other cases. 


19.2.59. Updateltem 
»»-aListControl^Updateltem(--item--)--------------------------- >< 
The UpdateItem method updates a list view item. 


Arguments: 


The only argument is: 


item 


The number of the item to be updated. 
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Return value: 


The item was updated. 
You did not specify item. 


For all other cases. 


19.2.60. Update 


2»-aListControl" Update--------------------2--c-c-- se ase sass >< 


The Update method updates a list view control. 


Return value: 


0. 


19.2.61. EnsureVisible 


+-0-+ 
»»-aListControl^EnsureVisible(--item--,--4---4--)-------------- >< 
+-1-+ 


The Ensure Visible method ensures that a list view item is entirely or partially visible by scrolling the list 
view control, if necessary. 


Arguments: 


The arguments are: 


item 


The number of the item visible. 
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partial 


Specifies whether the item must be entirely visible: 


The list view control is not scrolled if the item is at least partially visible. 


The list view control is scrolled if the item is only partially visible. This is the default. 


Return value: 


The item is visible. 
You did not specify item. 


For all other cases. 


19.2.62. setlmageList 


»»--setlmageList(--src-4*--------------- +-+---------- +-+---------- +-)----------- >< 
*-,-typeUrWidth-* +-,-height-+ +-,-ilType-+ 


Assigns, or removes, an image list for the list-view control. Using .nil for the first argument removes 
the current image list. 


The list-view control uses image lists for a number of things, the large icons, the small icons, the state 
images, and the group header images. (ooDialog does not yet support list-view groups.) The src 
argument can be either an ImageList object, or a single bitmap. 


Using an image list object is the most flexible option. The programmer creates the image list in the 
manner most suitable to the program. When the program is enhanced or changed it is easy to change the 
image list. 


When src is a single bitmap it is used in this way: A single bitmap is created that consists of all the 
images for the image list. All the images must be the same width and height. The images are arranged in 
the bitmap in a row, side-by-side, in the order they should appear in the image list. ooDialog uses this 
bitmap to create a ./mageList object and assigns it to the list-view. The src argument can be either the file 
name of the bitmap or a bitmap Image object. 


Although using a single bitmap will allow the programmer to save a couple of lines of code, it has a 
number of disadvantages. The image list is created with the exact number of images in the bitmap and no 
extra room to add images. The image list is created as an unmasked image list, with a color of 8 bit per 
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pixel. If the program is enhanced or changed in a way that requires even a slight change to the image list, 
the single bitmap would need to be re-created. 


When using a single bitmap, if the system fails to create the image list from the details supplied by 
ooDialog, the method of informing the programmer of the error is not as robust as it is when the 
programmer creates the image list herself. However, ooDialog will set the .SystemErrorCode variable for 
any cases where the operating system reports an error. Also note that when using a single bitmap, 
ooDialog will instantiate a ./mageList object. The programmer can retrieve this object using the 
getImageList() method and then manipulate it using the methods of the ImageList class. 


Unless a list-view has the LVS SHAREIMAGELISTS style, (corresponds to the SHAREIMAGES style 
in the addListControl() method,) the list-view control will handle releasing the image list(s). When the 
share image lists style is used, ownership of the image list remains with the programmer. The ImageList 
and Image classes are used to manage image lists and images in ooDialog. The documentation on both 
classes discusses when and why the programmer may want to release image lists. The Image class 
documentation has the most detail on this subject. 


Details 
Sets the .SystemErrorCode variable. 


Raises syntax errors when incorrect arguments are detected. 


Arguments: 


The arguments are: 


src 


The source for the image list. The most flexible way to use this method is to provide an image 
list object to assign to the list-view. 


However, as explained above, this argument can also be a single bitmap from which the image 
list is to be created. In this case, the argument can be either the file name of the bitmap or a 
bitmap Image object. 


If this argument is .nil the existing image list, if any, is removed. 


typeOrWidth 
Optional. 


type: When src is an ImageList object, this argument specifies which image list to assign, (or 
remove.) You can use .Image-toID() to get the correct numeric value for one of the following 


symbols: 
LVSIL NORMAL LVSIL SMALL 
LVSIL STATE 


or use the correct numeric value itself. Note that there is also a LVSIL_GROUPHEADER 
symbol, but ooDialog does not yet support it. The default is LVSIL. NORMAL. 


width: When src is a single bitmap, this argument can be used to specify the width of a single 
image in the bitmap. The default is the actual height of the bitmap. 


height 


Optional. This argument is only used when src is a single bitmap. In that case height specifies 
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the height of an image in the bitmap. The default is to use the actual height of the bitmap. 


ilType 


Optional. This argument is only used when src is a single bitmap. It is used to specify which 
image list is being assigned. Its usage is exactly the same as is documented for the type role of 
the typeOrWidth argument above. If omitted, the default is LVSIL_NORMAL. 


Return value: 


The existing image list is returned, if there is one. Otherwise, .nil is returned. 


Example: 


This is a complete working example. It creates an image list using the application icons that 
ooDialog makes available for general use. The image list is assigned as the normal icon image list. 


dlg = .ImageDisplay^new 
if dlg~initCode = 0 then do 
dlg^constDir[IDC LV. IMAGES] = 100 
dlg^create(30, 30, 320, 155, "ooDialog Icon Resources", , , "Tahoma") 
dlg^Execute("SHOWTOP", IDI_DLG_OOREXX) 
dlg^Deinstall 
end 


::requires "QODWIN32.CLS" 
::class ’ImageDisplay’ subclass UserDialog inherit AdvancedControls 
::method defineDialog 

self^addListControl(IDC LV IMAGES, , 10, 10, 300, 135, "ICON SINGLESEL"); 
::method initDialog 


names = .array~new() 

names[1] = "IDI_DLG_OODIALOG" 
names[2] = "IDI_DLG_APPICON" 
names[3] = "IDI_DLG_APPICON2" 
names[4] = "IDI_DLG_OOREXX" 


ids = .array~new() 

ids[1] = self~constDir[IDI_DLG_OODIALOG] 
ids[2] = self~constDir[IDI_DLG_APPICON] 
ids[3] = self~constDir [IDI_DLG_APPICON2] 
іаѕ [4] = self~constDir [IDI_DLG_OOREXX] 


11 
12 


SM_CXICON 
SM_CYICON 


size = .Size^new(.DlgUtil^getSystemMetrics(SM CXICON), .DlgUtil~ getSystemMetrics (SM_CYICON) ) 


oodModule = .Resourcelmage^new("oodialog.dll", self) 
icons = oodModule~getImages(ids, .Image^toID(IMAGE ICON), size) 
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flags = .DlgUtil~or(.Image~toID(ILC_COLOR24), .Image~toID(ILC_MASK) ) 
imageList = .ImageList^create(size, flags, 4, 0) 
imageList~ addImages (icons) 


list = self~getListControl (IDC_LV_IMAGES) 
list^setImageList(imagelist, .Image~toID(LVSIL_NORMAL) ) 


do і = 1 to ids^items 
list^add(names[i] ’(’?ids[i]’)’, i - 1) 
end 


19.2.63. getlmageList 


»»--getlmageList(--4-------- *--)------------------------------------ >< 
*--type--* 


Retrieves the current image list for the type specified. The default is to retrieve the image list for the 
normal icons. See the () method for infomation on assigning an image list to a list-view control. 


Details 


Raises syntax errors when incorrect arguments are detected. 


Arguments: 


The single optional argument is: 


type 
Optional. Specifies which image list to retrieve. You can use .Image-toID() to get the correct 


numeric value for one of the following symbols: 
LVSIL NORMAL LVSIL SMALL 
LVSIL STATE 


or use the correct numeric value itself. Note that there is also a LVSIL. GROUPHEADER symbol, 
but ooDialog does not yet support it. 


The default is LVSIL NORMAL. 


Return value: 


This method returns the current image list, if there is one. .nil is returned if there is no current 
image list of the type specified. 


Example: 


This example comes from a complex application that opens and closes a large number of dialogs 
and uses many list-view controls. АП the list-view controls share the same image lists. When the 
last dialog is closed, the shared image lists are released to free up system resources as the 
application enters its next phase. 


::method ok 
self^checkImageLists 
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return self^ok:super 


::method cancel 
self^checkImageLists 
return self^cancel:super 


::method checkImageLists 
expose list 


if self^amLastDialog then do 
types = .array^of(LVSIL NORMAL, LVSIL SMALL, LVSIL STATE) 


do type over types 
il = list~getImageList (type) 
if il \== .nil then il^release 
end 
end 


19.2.64. setSmalllmages (deprecated) 


Note: This method is deprecated. It is replaced by the functionally equivalent setlmageList() method. 
Do not use this method in new code. Try to migrate existing code to to the setImageList method. 
This method may not exist in future versions of ooDialog. 


19.2.65. setlmages (deprecated) 


Note: This method is deprecated. It is replaced by the functionally equivalent setlmageList() method. 
Do not use this method in new code. Try to migrate existing code to to the setImageList method. 
This method may not exist in future versions of ooDialog. 


19.2.66. removeSmalllmages (deprecated) 


Note: This method is deprecated. It is replaced by the functionally equivalent setlmageList() method. 
Do not use this method in new code. Try to migrate existing code to to the setImageList () method. 
This method may not exist in future versions of ooDialog. 
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19.2.67. removelmages (deprecated) 


Note: This method is deprecated. It is replaced by the functionally equivalent setlmageList() method. 
Do not use this method in new code. Try to migrate existing code to to the setImageList O method. 
This method may not exist in future versions of ooDialog. 


19.2.68. Find 


+- -1--+ +-0-+ 
>>-aListControl*Find(--text-- ,--+------ +====фе=шфе=е= jets >< 
+-item-+ +-1-+ 


The Find method searches for a list view item containing text. The text of this item must exactly match 


text. 


Arguments: 


The arguments are: 


text 


The text of the item to be searched for. 
item 


Specify the number of the item at which the search is to be started. Specify -1 or omit this 
argument to start the search at the beginning. 


wrap 


Specify 1 if the search is to be continued at the beginning if no match is found. Specify 0 or 
omit this argument if the search is to stop at the end of the list. 


Return value: 


The number of the item, or -1 in all other cases. 


19.2.69. FindPartial 


+- -1--+ +-0-+ 
»»-aListControl^FindPartial(--text--,--4------4--,--4---4--)---»« 
+-item-+ += 1+ 


The FindPartial method searches for a list view item containing text. An item matches if its text begins 


with fext. 
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Arguments: 


The arguments are: 


text 


The text of the item to be searched for. 


item 


Specify the number of the item at which the search is to be started. Specify -1 or omit this 
argument to start the search at the beginning. 


wrap 


Specify 1 if the search is to be continued at the beginning if no match is found. Specify 0 or 
omit this argument if the search is to stop at the end of the list. 


Return value: 


The number of the item, or -1 in all other cases. 


19.2.70. FindNearestXY 


»»-aListControl^FindNearestXY(--x--,--y--4-------------------- 4--)-»« 
| +-DOWN--+ | 
4-,--"--4-UP----4--"-4 

+-ЪЕЕТ--+ 
+-RIGHT-+ 


The FindNearestX Y method searches, in the specified direction, for the item nearest to the specified 
position. 


Arguments: 


The arguments are: 


x 
The x-coordinate of the position at which the search is to be started. 
y 
The y-coordinate of the position at which the search is to be started. 
direction 


The direction in which the search should proceed. 
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Return value: 


The index of the item, or -1 in all other cases. 


19.2.71. Arrange 


>>-aListControl~ Arrange 


The Arrange method aligns items according to the current alignment style of the list view control. 


Return value: 


The items were aligned. 


For all other cases. 


19.2.72. SnapToGrid 


»»-aListControl^SnapToGrid 


The SnapToGrid method snaps all icons to the nearest grid position. 


Return value: 


The items were snapped. 


For all other cases. 


19.2.73. AlignLeft 


»»-aListControl^AlignLeft 


The AlignLeft method aligns items along the left window border. 
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Return value: 


The items were aligned. 


For all other cases. 


19.2.74. AlignTop 


»»-aListControl^Alignlop--------------------2----5-----99-7---2-- 


The AlignTop method aligns items along the upper window border. 


Return value: 


The items were aligned. 


For all other cases. 


19.2.75. ItemPos 


»»-aListControl^ItemPos(--item--)------------------------------ >< 


The ItemPos method retrieves the position of the upper left corner of the item. 


Arguments: 


The only argument is: 


item 


The number of the item. 


Return value: 
The x- and y-coordinates of the upper left corner of the item, or -1 if you did not specify item, or 0 


in all other cases. 
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Note: Use DefListDragHandler to support default dragging: 


self~ConnectListNotify (104, "BEGINDRAG" ,"DefListDragHandler") 


19.2.76. SetltemPos 


+-0-+ +-0-+ 
»»-aListControl^SetItemPos(--item--,--4---4--,--4---4--)-------»« 
+-х-+ +-у-+ 


The SetItemPos method moves ап item to a specified position in a list view control, which must be in 
icon or small-icon view. 


Arguments: 


The arguments are: 


item 


The number of the item. 


The x-coordinate of the new position of the upper left corner of the item, in view coordinates. 
The default is 0. 


The y-coordinate of the new position of the upper left corner of the item, in view coordinates. 
The default is 0. 


Return value: 


The item was moved. 


You did not specify item. 


For all other cases. 


Note: Use DefListDragHandler to support default dragging: 
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self~ConnectListNotify (104, "BEGINDRAG" ,"DefListDragHandler") 


19.2.77. Edit 


»»-aListControl^Edit(--item--)--------------------------------- >< 


The Edit method begins editing of the text of the specified list view item. 


Arguments: 


The only argument is: 


item 


The number of the item. 


Return value: 


The handle of the edit control used to edit the item text, or O in all other cases. 


19.2.78. EndEdit 


>2-аГа в СопъгоЕпЧЕД1Е---<- 5 --- + #------- eere >< 


The EndEdit method cancels editing of the list view item that is being edited. 


19.2.79. SubclassEdit 


»»-aListControl^SubclassEdit----------------------------------- >< 


The SubclassEdit method is used by the DefListEditHandler to correct an operating system problem if 
the Esc or Enter key was pressed in an active edit control. 


19.2.80. RestoreEditClass 


»»-aListControl^RestoreEditClass------------------------------- >< 


The RestoreEditClass method is used by the DefListEditHandler to correct an operating system problem 
if the Esc or Enter key was pressed in an active edit item. 
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19.2.81. НетзРегРаде 


»»-aListControl'ItemsPerPage----------------------------------- >< 


The ItemsPerPage method calculates the number of items that vertically fit the visible area of a list view 
control that is in list or report view. Only fully visible items are counted. 


Return value: 


The number of fully visible items. If the current view is an icon or small-icon view, the return value 
is the total number of items in the list view control. 


19.2.82. Scroll 


+-0-+ +-0-+ 
»»-aListControl^Scroll(--4---4--,--4---4-- )-------------------- >< 
+-х-+ +-у-+ 


The Scroll method scrolls the content of a list view control. 


Arguments: 


The arguments are: 


x 
An integer value specifying the amount of horizontal scrolling. If the control is in icon, 
small-icon, or report view, this value specifies the number of pixels to be scrolled. If it is in list 
view, this value specifies the number of columns to be scrolled. The default value is 0. 

y 


An integer value specifying the amount of vertical scrolling. If the control is in icon, 
small-icon, or report view, this value specifies the number of pixels to be scrolled. If it is in list 
view, this value specifies the number of lines to be scrolled. The default value is 0. 


Return value: 


Scrolling was successful. 


Scrolling failed. 
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19.2.83. BkColor 


22-aListControl BkGolor-----------—---—---mcm Ses Sse Ss Ss Sse eec >< 


The BkColor method retrieves the background color for a list view control. 


Return value: 


The color-palette index specifier (О to 18). For more information on color palettes, refer to 
Definition of Terms. 


19.2.84. BkColor= 


»»-aListControl^BkColor-(--color--)---------------------------- >< 


The BkColor= method sets the background color of a list view control. 


Arguments: 


The only argument is: 


color 


The new background color. Specify the color-palette index specifier (0 to 18). For more 
information on color palettes, refer to Definition of Terms. 


Example: 
The following example sets the background color of a list control to yellow: 


::method Yellow 
curList = self~GetListControl (104) 
curList^BkColor = 15 
curList”~ Update 


19.2.85. TextColor 


2»-aListControl TextColor-------------------cce seas Sea узышы >< 


The TextColor method retrieves the text color of a list view control. 


Return value: 


The color-palette index specifier (0 to 18). For more information on color palettes, refer to 
Definition of Terms. 
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19.2.86. TextColor= 


»»-aListControl^TextColor-(--color--)-------------------------- >< 


The TextColor= method sets the text color of a list view control. 


Arguments: 


The only argument is: 


color 


The new text color. Specify the color-palette index specifier (0 to 18). For more information on 
color palettes, refer to Definition of Terms. 


Example: 
The following example sets the text color of a list control to light blue: 


::method LightBlue 
curList = self^GetListControl(104) 
curList^BkColor = 9 
curList^Update 


19.2.87. TextBkColor 


2»-aListControl Техъ ВкСоПог-------------------------< >< 


The TextBkColor method retrieves Ше background color of Ше text in a list view control. 


Return value: 


The color-palette index specifier (0 to 18). For more information on color palettes, refer to 
Definition of Terms. 


19.2.88. TextBkColor= 


»»-aListControl^TextBkColor-(--color--)------------------------ >< 


The TextBkColor= method sets the background color for the text in a list view control. 
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Arguments: 


The only argument is: 


color 


The new background color for text. Specify the color-palette index specifier (0 to 18). For more 
information on color palettes, refer to Definition of Terms. 


19.3. Notification Messages 


The list view control sends notification messages to its parent (the dialog) when certain events happen. 
For more information on notification messages, refer to ConnectListNotify. 


The following example shows how to connect the list view notification messages with the corresponding 
message: 


::method Init 
use arg InitStem. 
if Arg(1,"o") = 1 then 
InitRet - self^Init:super 
else 
InitRet = self^Init:super(InitStem.) 


if self^Load("list.rc", ) \= O then do 
self^InitCode - 1 
return 
end 


/* Connect dialog control items to class methods */ 
self^ConnectListNotify ("ТС LIST","Changing","OnChanging. С LIST") 
self^ConnectListNotify("IDC LIST", "Changed", "UÜnChanged, ТОС LIST") 
self^ConnectListNotify("IDC, LIST" , "DefaultEdit") 
self^ConnectListNotify("IDC, LIST" , "Delete","OnDelete  IDC LIST") 
self^ConnectListNotify("IDC, LIST" , "KeyDown" , "UÜnKeyDown, IDC, LIST") 
self^ConnectButton("IDC, PB NEW","IDC PB NEW") 
self^ConnectButton("IDC PB, DELETE","IDC. PB DELETE") 
self^ConnectButton(2,"Cancel") 

self^ConnectButton(9,"Help") 

self^ConnectButton(1,"OK") 

return InitRet 
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The tree view control is a dialog that displays a hierarchical list of items, such as the headings in a 
document, the entries in an index, or the files and directories on a disk. Each item consists of a label and 
an optional image bitmap, and can have a list of subitems associated with it. By clicking on an item, the 
user can expand and collapse the associated list of subitems. 


Refer to OODTREE.REX in the OODIALOG\SAMPLES directory for an example. 


Requires: 


The TreeControl class requires the class definition file oodwin32.cls: 


::requires "oodwin32.cls" 


Methods: 


Instances of the TreeControl class implement the methods listed in the TreeControl Instance 


Methods table. 


Table 20-1. TreeControl Instance Methods 













































































Method... ..оп page 

Add Add 

Child Child 

Collapse Collapse 
CollapseAndReset CollapseAndReset 
Delete Delete 

DeleteAll DeleteAll 
DropHighlight DropHighlight 
DropHighlighted DropHighlighted 
Edit Edit 

EndEdit EndEdit 
EnsureVisible Ensure Visible 
Expand Expand 
FirstVisible First Visible 
HitTest HitTest 

Indent Indent 

Indent= Indent= 

Insert Insert 

IsAncestor IsAncestor 
ItemInfo ItemInfo 

Items Items 

MakeFirst Visible MakeFirst Visible 
Modify Modify 
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Method... ...оп page 

Moveltem Moveltem 

Next Next 

NextVisible Next Visible 

Parent Parent 

Previous Previous 

Previous Visible Previous Visible 
Removelmages (deprecated) Removelmages (deprecated) 
RestoreEditClass RestoreEditClass 

Root Root 

Select Select 

Selected Selected 

SetImages (deprecated) SetImages (deprecated) 
SortChildren SortChildren 
SubclassEdit SubclassEdit 

Toggle Toggle 

VisibleItems VisibleItems 








20.1. Methods of the TreeControl Class 


The following sections describe the individual methods of the TreeControl class. 


20.1.1. Insert 


+-"LAST"--+ +-""---+ +-0----- + 
»»-aTreeControl^Insert(--parent--,--*-after---4--,--*------4--,--4-------4--,--5 
+-"FIRST"-+ +-Ъехъ-+ +-ішаре-+ 
+-"SORT"--+ 
+-"0"-+ 
>--+---------- +--,--+------------------------ +--,--+----- +--)-->< 
+-selImage-+ | +-------------- + | +-"1"-+ 
| V | | 
+-"----+-EXPANDED-+-+--"-+ 
+-BOLD----- + 


The Insert method inserts a new item in a tree view control. 


Arguments: 


The arguments are: 
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parent 


The handle to the parent item. If you specify "ROOT", the item is inserted at the root of the 
tree view control. 


after 


The handle to the item after which the new item is to be inserted or one of the following values: 


"FIRST" 


Inserts the item at the beginning of the list. 


"LAST" 


Inserts the item at the end of the list. This is the default. 


"SORT" 


Inserts the item into the list in alphabetical order. 


text 


пи 


The text for Ше item. If you omit this argument, "" is assumed. 


image 


The index of the icon image in the tree view control’s bitmap file to be used when the item is in 
the non-selected state. If you omit this argument, the icon with index 0 is used. 


selImage 


The index of the icon image in the tree view control's bitmap file to be used when the item is in 
the selected state. If you omit this argument, the icon specified for image is used. 


state 


Specifies the appearance and functionality of the item. It can be a combination of the following 
values, separated by a blank: 


EXPANDED 


The item is currently expanded with all child items visible. This only applies to parent 
items. 


BOLD 
The item is shown in bold. 


If you omit this argument, the item is inserted in collapsed and normal form. 


children 


Indicates whether the item has child items associated with it: 
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"0" 


The item has no child items, which is the default. 


" 1 " 
The item has one or more child items. 


You can use this argument to show an item that does not have any child items, with an 
expand button. This allows you to save memory usage by dynamically loading and 
displaying the child items only when the user expands the item. 


Return value: 


The handle to the new item, or O for all other cases. 


Example: 
The following example inserts child items when a specific root item is expanded. The text strings 
for the items are loaded from a file. 


::method OnExpanding. IDC TREE 
use arg tree, item 


itemFile - "root6.inp" 
curTree = self^GetTreeControl("IDC TREE") 
itemInfo. = curTree^ItemInfo(item) 


if itemInfo.!TEXT = "Root 6" & \itemInfo.!STATE~POS("EXPANDED") then 
do 


do while lines(itemFile) 
line = linein(itemFile) 
command = "curTree^Insert(item, ," | 11іпе||")" 
interpret command 
end 
curTree~ Expand (item) 
end 


20.1.2. Add 


+------- + 
V | +-""---+ +-0----- + 
»»-aTreeControl^Add(----4---4-4--,--4------4--,--4-------4--,---»5 
T2, +-text-+ +-image-+ 
+-"0"-+ 
>--+---------- +--,--+------------------------ +--,--+----- +--)-->< 
+-selImage-+ | +-------------- + | +-"1"-+ 
| V | | 
+-"----+-EXPANDED-+-+--"-+ 
+-BOLD----- + 
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The Add method adds a new item to a tree view control. 


Arguments: 


The arguments are: 


The number of commas specifies at which parent the item is to be inserted. If you omit this 
argument, the item is inserted as a root item. Each additional comma inserts the item one level 
deeper than the item inserted previously. See the example in the following. 


text 


пи 


The text for Ше item. If you omit this argument, "" is assumed. 


image 
The index of the icon image in the tree view control’s bitmap file to be used when the item is in 
the non-selected state. If you omit this argument, the icon with index 0 is used. 

selImage 
The index of the icon image in the tree view control's bitmap file to be used when the item is in 
the selected state. If you omit this argument, the icon specified for image is used. 

state 


Specifies the appearance and functionality of the item. It can be a combination of the following 
values, separated by a blank: 


EXPANDED 


The item is currently expanded with all child items visible. This only applies to parent 
items. 


BOLD 
The item is shown in bold. 


If you omit this argument, the item is inserted in collapsed and normal form. 


children 


Indicates whether the item has child items associated with it: 


"0" 

The item has no child items, which is the default. 
" 1 " 

The item has one or more child items. 


You can use this argument to show an item that does not have any child items, with an 
expand button. This allows you to save memory usage by dynamically loading and 
displaying the child items only when the user expands the item. 
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Return value: 


The handle to the new item, or 0 for all other cases. 


Example: 
To get the following tree view: 
* Peter 
- Mike 
* George 
* Monique 


• John 


* Chris 


- Maud 


e Ringo 


* Paul 
• Dave 
* Sam 


. Jeff 


* Mary 
• Helen 
* Michelle 


• Diana 


your example must look as follows: 


::method InitDialog 
InitDlgRet - self^InitDialog:super 
curTree = self^GetTreeControl("IDC, TREE") 
if curTree \= .Nil then 
do 
curTree^Add("Peter", , ,"BOLD EXPANDED") 
curTree^Add(," Mike", , ,"EXPANDED") 
curTree^Add(, ,"George") 
curTree^Add(, ,"Monique") 
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curTree^Add(, , ,"John") 

curTree~Add(, ,"Chris") 
curTree^Add(,"Maud") 
curTree^Add(,"Ringo") 
curTree^Add("Paul", , ,"BOLD EXPANDED") 
curTree^Add(,"Dave") 
curTree^Add(,"Sam") 
curTree^Add(,"Jeff") 
curTree^Add("Mary", , ,"BOLD EXPANDED") 
curTree^Add(,"Helen") 
curTree^Add(,"Michelle") 
curTree^Add(,"Diana") 


end 


20.1.3. Modify 


+-""---+ +-0----- + 
»»-aTreeControl^Modify (--hItem--,--4------4--,--4-------4--,--4------------,--5 
+-text-+ +-1шаре-+ +-selImage-+ 
+-"0"-+ 
>--+------------------------------- +--,--+----- +--)------------ >< 
| +--------------------- + | +-"1"-+ 
| V | | 
*-"----4-BOLD------------ +-+--"-+ 
+-NOTBOLD--------- + 
t-DROP------------ * 
*-NOTDROP--------- + 
+-SELECTED-------- + 
+-NOTSELECTED----- + 
+-CUT------------- + 
+-NOTCUT---------- + 


+-EXPANDEDONCE----+ 
+-NOTEXPANDEDONCE-+ 
+-ЕХРАМрЕр-------- + 
+-МОТЕХРАМрЕр----- + 


The Modify method sets some or all attributes of an item of a tree view control. 


Arguments: 


The arguments are: 


hItem 


The handle to the item to be modified. 


text 


пи 


The text for Ше item. If you omit this argument, "" is assumed. 
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image 


The index of the icon image in the tree view control’s bitmap file to be used when the item is in 
the non-selected state. If you omit this argument, the icon with index 0 is used. 


selImage 


The index of the icon image in the tree view control's bitmap file to be used when the item is in 
the selected state. If you omit this argument, the icon specified for image is used. 


state 


Specifies the appearance and functionality of the item. It can be one or more of the following 
values, separated by blanks: 


BOLD 


The item is shown in bold. 


NOTBOLD 


The item is not bold. 


DROP 


The item is selected as a drag-and-drop target. 


NOTDROP 


The item is not selected as a drag-and-drop target. 


SELECTED 


The item is selected. Its appearance depends on whether it has the focus and whether the 
system colors are used for the selection. 


NOTSELECTED 


The item is not selected. 


CUT 


The item is selected as part of a cut-and-paste operation. 


NOTCUT 


The item is not selected as part of a cut-and-paste operation. 


EXPANDEDONCE 


The item's list of child items has been expanded at least once. 


NOTEXPANDEDONCE 


The item's list of child items has not been expanded at least once. 
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EXPANDED 


The item’s list is currently expanded with all child items visible. This only applies to 
parent items. 


NOTEXPANDED 


The item’s list is currently not expanded. 


children 


Indicates whether the item has child items associated with it: 


"0" 

The item has no child items, which is the default. 
" 1 " 

The item has one or more child items. 


You can use this argument to show an item that does not have any child items, with an 
expand button. This allows you to save memory usage by dynamically loading and 
displaying the child items only when the user expands the item. 


Return value: 


0 
The item has been modified. 
-1 
For all other cases. 
Example: 


The following example changes the text of the item to bold when it is selected: 


::method OnSelChanging. IDC TREE 
curTree = self^GetTreeControl("IDC, TREE") 
curTree^Modify(curTree^selected, , , ,"BOLD") 


20.1.4. ItemInfo 


»»-aTreeControl^ItemInfo(--hItem--)---------------------------- >< 


The ItemInfo method retrieves some or all attributes of an item of a tree view control. 
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Arguments: 


The only argument is: 


hItem 


The handle to the item of which attributes are to be retrieved. 


Return value: 


A compound variable that stores the attributes of the item, or -1 in all other cases. The compound 
variable can be: 


RetStem.!TEXT 


The text of the item. 


RetStem.'CHILDREN 


The item has children. 


The item has no children. 


RetStem.' IMAGE 


The index of the icon image in the tree view control's bitmap file used when the item is in the 
non-selected state. 


RetStem.'SELECTEDIMAGE 


The index of the icon image in the tree view control's bitmap file used when the item is in the 
selected state. 


RetStem.! STATE 


An empty string or one or more of the following strings, separated by blanks: 


EXPANDED 


The item's list is currently expanded with all child items visible. This only applies to 
parent items. 


BOLD 


The item is in bold. 


SELECTED 


The item is selected. 
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EXPANDEDONCE 


The item’s list has been expanded at least once. This only applies to parent items. 


INDROP 


The item is selected as a drag-and-drop target. 


Example: 


The following example displays the attributes of the selected item: 


::method Info 
curTree = self~GetTreeControl ("IDC_TREE") 
itemInfo. = curTree^ItemInfo(curTree^Selected) 
say itemInfo. ! TEXT 
say itemInfo. ! CHILDREN 
say itemInfo.! IMAGE 
say itemInfo.!STATE 


20.1.5. Items 


2»-alreeControl Items---—--——-—--—-------------- шн а эч уны шше >< 


The Items method retrieves the number of items in a tree view control. 


Return value: 


The number of items. 


Example: 


The following example counts all items in a tree view control: 


::method Count 
curTree = self^GetTreeControl("IDC, TREE") 
say curTree^Items 


20.1.6. Visibleltems 


»»-aTreeControl^Visibleltems----------------------------------- >< 


The VisibleItems method obtains the number of items that can be fully visible in a tree view control. This 
number can be greater than the number of items in the control. The control calculates this value by 
dividing the height of the client window by the height of an item. 
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Return value: 
The number of items that can be fully visible. For example, if you can see all of 19 items and part of 
another item, the return value is 19, not 20. 

Example: 
The following example returns the number of items that can be fully visible: 


::method Visible 
curTree = self^GetTreeControl("IDC TREE") 
say curTree~VisibleItems 


20.1.7. Root 


>> -аТгееСопъго!Коо--------------------------------- >< 


The Root method retrieves Ше first or topmost item of the tree view control. 


Return value: 


The handle to the first item, or O in all other cases. 


Example: 
The following example displays the name of the root item: 


::method RootName 
curTree = self^GetTreeControl("IDC, TREE") 
itemInfo. = curTree^ItemInfo(curTree^Root) 
say ItemInfo.!Text 


20.1.8. Parent 


»»-aTreeControl^Parent (--hItem--)------------------------------ >< 


The Parent method retrieves the parent of the specified item. 


Arguments: 


The only argument is: 


hItem 


The handle to the item for which the parent is to be retrieved. 


Return value: 


The handle to the parent item, or -1 if Пет is not specified or is 0, or 0 in all other cases. 
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Example: 


The following example displays the name of the selected item’s parent: 


::method Parent 
curTree = self^GetTreeControl("IDC, TREE") 
itemInfo. = curTree^ItemInfo(curTree^Parent(curTree^Selected)) 
say ItemInfo. !Text 


20.1.9. Child 


»»-aTreeControl^Child(--hItem--)------------------------------- >< 


The Child method retrieves the first child item of ЛПет. 


Arguments: 


The only argument is: 


Һет 


The handle to the item of which the first child is to be retrieved. 


Return value: 


The handle to the first child item, or -1 if you omitted Ает, ог 0 in all other cases. 


Example: 


The following example displays the name of parent of the selected item: 


::method Child 
curTree = self^GetTreeControl("IDC TREE") 
itemInfo. = curTree^ItemInfo(curTree^Child(curTree^Selected)) 
say ItemInfo.!Text 


20.1.10. Selected 


»»-aTreeControl^Selected--------------------------------------- >< 


The Selected method retrieves the currently selected item. 
Return value: 
The handle to the currently selected item, or 0 in all other cases. 


Example: 


The following example displays the name of the selected item: 


::method SelectedName 
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curTree = self^GetTreeControl("IDC, TREE") 
itemInfo. = curTree^ItemInfo(curTree^Selected) 
say ItemInfo. !Text 


20.1.11. DropHighlighted 


»»-aTreeControl^DropHighlighted-------------------------------- >< 


The DropHighlighted method retrieves the item that is the target of a drag-and-drop operation. 


Return value: 


The handle to the item, or 0 in all other cases. 


20.1.12. FirstVisible 


»»-aTreeControl^FirstVisible----------------------------------- >< 


The FirstVisible method retrieves the first visible item in the client window of a tree view control. 


Return value: 


The handle to the first visible item, or O in all other cases. 


Example: 


The following example displays the name of the first visible item: 


::method FirstVisibleName 
curTree = self^GetTreeControl("IDC TREE") 
itemInfo. = curTree^ItemInfo(curTree^FirstVisible) 
say ItemInfo.!Text 


20.1.13. Next 


»»-aTreeControl^Next (--hItem--)-------------------------------- >< 


The Next method retrieves the sibling item next to ЛПет. 


Arguments: 


The only argument is: 


hItem 


The handle to the item next to the sibling item to be retrieved. 
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Return value: 


The handle to the next sibling item, or -1 if you omitted hJtem, or 0 in all other cases. 


Example: 


The following example displays the name of the selected item and its siblings: 


::method SiblingNames 

curTree = self^GetTreeControl("IDC TREE") 

nextItem = curTree^Selected 

do while nextItem \= 0 
itemInfo. = curTree^ItemInfo(nextItem) 
say ItemInfo. !Text 
nextItem = curTree^Next (nextItem) 

end 


20.1.14. NextVisible 


»»-aTreeControl^NextVisible(--hItem--)------------------------- >< 


The NextVisible method retrieves the visible item following Atem. 


Arguments: 


The only argument is: 


hItem 


The handle to the item that precedes the visible item to be retrieved. hJtem must also be visible. 


Return value: 


The handle to the next visible item, or -1 if you omitted Atem, or 0 in all other cases. 


20.1.15. Previous 


»»-aTreeControl^Previous(--hItem--)---------------------------- >< 


The Previous method retrieves the sibling item preceding hJtem. 


Arguments: 


The only argument is: 


hItem 


The handle to the item that follows the sibling item to be retrieved. 
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Return value: 


The handle to the previous sibling item, or -1 if hItem is not specified or is 0, or O in all other cases. 


20.1.16. PreviousVisible 
»»-aTreeControl^PreviousVisible(--hItem--)--------------------- >< 
The Previous Visible method retrieves the visible item preceding Пет. 


Arguments: 


The only argument is: 


hItem 


The handle to the item that follows the visible child item to be retrieved. ет must also be 


visible. 


Return value: 


The handle to the previous visible child item, or -1 if Пет is not specified or is 0, or O in all other 


cases. 


20.1.17. Delete 


»»-aTreeControl^Delete(--hItem--)------------------------------ >< 


The Delete method removes an item from a tree view control. 


Arguments: 


The only argument is: 


hItem 


The handle to the item to be deleted. 


Return value: 


The item was deleted. 


An error occurred. 
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АПет is О or is not a valid value. 


Example: 
The following example deletes the selected item and all its children, if any: 


::method ТОС PB DELETE 
curTree = self^GetTreeControl("IDC, TREE") 
curTree^Delete(curTree^Selected) 


20.1.18. DeleteAll 


>>-аТгееСопъго! Петеред  1-----------------------------< >< 


The DeleteAll method removes all items from a tree view control. 


Return value: 


The items were removed. 


For all other cases. 


20.1.19. Collapse 


»»-aTreeControl^Collapse(--hItem--)---------------------------- >< 


The Collapse method collapses the list of child items associated with the specified parent item. 


Arguments: 


The only argument is: 


hItem 


The handle to the parent item to collapse. 
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Return value: 


0 
The list of child items has collapsed. 
-1 
hItem is not specified or is 0. 
1 
For all other cases. 
Example: 


The following example collapses the selected item: 


::method CollapseSelected 
curTree = self~GetTreeControl ("IDC_TREE") 
curTree^Collapse(curTree^Selected) 


20.1.20. CollapseAndReset 


»»-aTreeControl^CollapseAndReset (--hItem--)-------------------- >< 


The CollapseAndReset method collapses the list of child items associated with the specified parent item 
and removes the child items. 


Arguments: 


The only argument is: 


hItem 


The handle to the parent item to collapse. 


Return value: 


The list of child items has collapsed and the child items have been removed. 


hItem is not specified or is 0. 
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For all other cases. 


Example: 
The following example collapses the selected item and removes all its child items: 


::method CollapseSelectedAndReset 
curTree = self^GetTreeControl("IDC, TREE") 
curTree^CollapseAndReset (curTree~ Selected) 


20.1.21. Expand 


»»-aTreeControl^Expand(--hItem--)------------------------------ >< 


The Expand method expands the list of child items associated with the specified parent item. 


Arguments: 


The only argument is: 


hItem 


The handle to the parent item to be expanded. 


Return value: 


0 
The parent item was expanded. 
-1 
hItem is not specified or is 0. 
1 
For all other cases. 
Example: 


The following example expands the selected item: 


::method ExpandSelected 
curTree = self^GetTreeControl("IDC, TREE") 
curTree~Expand(curTree~ Selected) 
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20.1.22. Toggle 


»»-aTreeControl^Toggle(--hItem--)------------------------------ >< 


The Toggle method collapses the list of the specified item if it was expanded, or expands it if it was 


collapsed. 


Arguments: 


The only argument is: 


Һет 


The handle to the item to be expanded or collapsed. 


Return value: 


0 
The item was expanded or collapsed. 
-1 
hItem is not specified or is 0. 
1 
For all other cases. 
Example: 


The following example toggles between expanding and collapsing a selected item: 


::method ToggleSelected 
curTree = self^GetTreeControl("IDC TREE") 
curTree” Toggle (curTree~ Selected) 


20.1.23. EnsureVisible 


»»-aTreeControl^EnsureVisible(--hItem--)----------------------- >< 


The Ensure Visible method ensures that a tree view item is visible, expanding the parent item or scrolling 


the tree view control, if necessary. 
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Arguments: 


The only argument is: 


hItem 


The handle to the item to be visible. 


Return value: 


The items in the tree view control were scrolled to ensure that the specified item is visible. 


hItem is not specified or is 0. 


For all other cases. 


20.1.24. Indent 


22»-salreeControl^Indent------------—-5---c-eMceee cene нн >< 


The Indent method retrieves the amount, in pixels, by which the child items are indented relative to their 
parent item. 


Return value: 


The amount indented, in pixels. 


20.1.25. Indent= 


»»-aTreeControl^Indent---indent-------------------------------- >< 


The Indent= method sets the width of indentation for а tree view control and redraws the control to 
reflect the new width. 
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Arguments: 


The only argument is: 


indent 


The width of the indentation, in pixels. If you specify a width that is smaller than the 
system-defined minimum, it is set to the system-defined minimum. 


Return value: 


-1 if indent is 0. 


20.1.26. Edit 


»»-aTreeControl^Edit(--hItem--)-------------------------------- >< 


The Edit method starts editing the text of the specified item by replacing the text with a single-line edit 
control containing this text. It implicitly selects and focuses the specified item. 


Arguments: 


The only argument is: 


hItem 


The handle to the item to be edited. 


Return value: 


The handle to the edit control used to edit the item text, or -1 if Пет is not specified or is 0, or 0 in 
all other cases. 


20.1.27. EndEdit 


»»-aTreeControl^EndEdit(--4-------- *--)------------------------ >< 
+-сапсе1-+ 


The EndEdit method ends the editing of the item label of the tree view. 


Arguments: 


The only argument is: 


cancel 


Indicates whether editing is canceled without being saved to the label. If you specify "1" or 
"YES", editing is canceled. Otherwise, the changes are saved to the label, which is the default. 
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Return value: 


Editing has ended successfully. 


For all other cases. 


20.1.28. SubclassEdit 


»»-aTreeControl^SubclassEdit----------------------------------- >< 


The SubclassEdit method is used by the DefTreeEditHandler to correct the problem occurring when Esc 
or the Enter key is pressed in an active edit item. 


20.1.29. RestoreEditClass 


>>-aTreeControl~“RestoreEditClass------------------------------- >< 


The RestoreEditClass method is used by the DefTreeEditHandler to correct the problem occurring when 
Esc or the Enter key is pressed in an active edit item. 


20.1.30. Select 


»»-aTreeControl^Select (--hItem--)------------------------------ >< 


The Select method selects a specific item. 


Arguments: 


The only argument is: 


Һет 


The handle to the item to be selected. 
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Return value: 


The item was selected. 


hItem was not specified or is 0. 


For all other cases. 


20.1.31. MakeFirstVisible 


»»-aTreeControl^MakeFirstVisible(--hItem--)-------------------- >< 


The MakeFirstVisible method ensures that Atem is visible and displays it at the top of the control’s 
dialog, if possible. If the specified item is near the end of the control’s hierarchy of items, it might not 
become the first visible item depending on how many items fit in the dialog. 


Arguments: 


The only argument is: 


hItem 


The handle to the item to be visible first. 


Return value: 


The item is visible first. 


hItem was not specified or is 0. 


For all other cases. 
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20.1.32. DropHighlight 


»»-aTreeControl^DropHighlight (--hItem--)----------------------- >< 


The DropHighlight method redraws Пет in the style used to indicate the target of a drag-and-drop 
operation. 


Arguments: 


The only argument is: 


hItem 


The handle of the item to be redrawn. 


Return value: 


The item was redrawn. 
hItem was not specified or is 0. 


For all other cases. 


20.1.33. SortChildren 
»»-aTreeControl^SortChildren(--hItem--)------------------------ >< 
The SortChildren method sorts the child items of the specified parent item in a tree view control. 


Arguments: 


The only argument is: 


hItem 


The handle to the parent item the child items of which are to be sorted. 
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Return value: 


The child items were sorted. 
hItem was not specified or is 0. 


For all other cases. 


20.1.34. setlmageList 


»»--setImagelist(--newImagelist--4---------- --)-------------------- >< 
+-- „-ъуре--+ 


Assigns, or removes, an image list for Ше tree-view control. Using .nil for the first argument removes 
the current image list. Tree-view controls can have two image lists. The normal image list, which 
contains selected, nonselected, and overlay images for the items of a tree-view control. And, the state 
image list. The state images can be used by the programmer to indicate application-defined item states. A 
state image is displayed to the left of an item’s selected or nonselected image. 


The tree-view control does not destroy an image list that is associated with it. The programmer must 
destroy the image list separately, if desired. This is useful if the same image list is assigned to multiple 
tree-view controls. In essence, the ownership of the image list remains with the programmer. The 
ImageList and Image classes are used to manage image lists and images in ooDialog. The documentation 
on both classes discusses when and why the programmer may want to release image lists. The Image 
class documentation has the most detail on this subject. 


Details 


Raises syntax errors when incorrect arguments are detected. 


Arguments: 


The arguments are: 


newImageList 


The image list to assign to the tree-view. If this argument is .nil the existing image list, if any, 
is removed. 


type 
Optional. Specifies which image list to assign, (or remove.) You can use .Image-toID() to get 


the correct numeric value for one of the following symbols: 
TVSIL NORMAL TVSIL STATE 
or use the correct numeric value itself. 
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The default is TVSIL. NORMAL. 


Return value: 


The existing image list is returned, if there is one. Otherwise, .nil is returned. 


Example: 
This example creates an image list and assigns it to the tree-view control for use as the normal 
image list. 


/* set images for the items */ 
image = .Image~getImage("bmp\psdemotv. bmp") 
imageList = .ImageList^create(.Size^new(32, 32), .Image^toID(ILC COLOR8), 10, 0) 
if Mimage^isNull, \imageList~isNull then do 
imageList~ add (image) 
tc^setImagelist(imageList, .Image~toID(TVSIL_NORMAL) ) 
image” release 
end 


20.1.35. getlmageList 


»»--getlmageList(--4-------- *--)------------------------------------ >< 
+--туре--+ 


Retrieves Ше current image list for Ше type specified. The default is to retrieve Ше tree-views normal 
image list. See the () method for infomation on assigning an image list to a tree-view control. 


Details 


Raises syntax errors when incorrect arguments are detected. 


Arguments: 


The single optional argument is: 


type 
Optional. Specifies which image list to retrieve. You can use .[mage~toID() to get the correct 


numeric value for one of the following symbols: 
TVSIL NORMAL TVSIL STATE 
or use the correct numeric value itself. 


The default is TVSIL. NORMAL. 


Return value: 


This method returns the current image list, if there is one. .nil is returned if there is no current 
image list of the type specified. 
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Example: 
This example releases the tree-view’s image lists, if they exist, when the dialog ends. 
::method ok 


self~doImageLists return self~ok:super 


::method cancel 
self~doImageLists 
return self^cancel:super 


::method odImageLists 
expose treeView 


types = .array^of(TVSIL NORMAL, TVSIL STATE) 
do type over types 
il = treeView~ getImageList (type) 


if il \== .nil then il^release 
end 


20.1.36. setlmages (deprecated) 


Note: This method is deprecated. It is replaced by the functionally equivalent setlmageList() method. 
Do not use this method in new code. Try to migrate existing code to to the setImageList O method. 
This method may not exist in future versions of ooDialog. 


20.1.37. removelmages (deprecated) 


Note: This method is deprecated. It is replaced by the functionally equivalent setlmageList() method. 
Do not use this method in new code. Try to migrate existing code to to the setImageList( method. 
This method may not exist in future versions of ooDialog. 


20.1.38. HitTest 


»»-aTreeControl^HitTest(--x--,--y--)--------------------------- >< 


The HitTest method determines the location of the specified point relative to the client area of a tree view 
control. 
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Arguments: 


The arguments are: 


The x-coordinate of the point. 


The y-coordinate of the point. 


Return value: 


О if no item occupies the point, or one or more of the following strings if an item occupies the 
specified point: 


handle 


The handle to the item that occupies the specified point. 


ABOVE 


Above the client area. 


BELOW 


Below the client area. 


NOWHERE 


In the client area but below the last item. 


ONITEM 


On the bitmap or label associated with an item. 


ONBUTTON 


On the button associated with an item. 


ONICON 


On the icon associated with an item. 


ONINDENT 


In the indentation associated with an item. 


ONLABEL 


On the label (string) associated with an item. 


ONRIGHT 


In the area to the right of an item. 
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ONSTATEICON 


On the state icon for a tree view item that is in a user-defined state. 


TOLEFT 


To the left of the client area. 


TORIGHT 


To the right of the client area. 


20.1.39. Moveltem 


»»-aTreeControl^Moveltem(--hItem--,--hNewParent--,--redraw--4--------------- +--)->< 
++, --"NODELETE"-+ 
+-,--"SIBLINGS"-+ 


The Moveltem method moves an item to a new location. 


Arguments: 


The arguments are: 
hItem 
The handle to the item to be moved. 


hNewParent 


The handle to the new parent to which the item is to be moved. 


redraw 


The tree view control is updated. 
options 

One of the following options: 

"NODELETE" 


The item is copied to another location. 


"SIBLINGS" 


Siblings are moved together with the item. 


Return value: 


The handle to the new parent, or O in all other cases. 
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20.1.40. IsAncestor 


»»-aTreeControl^IsAncestor(--hParent--,--hItem--)-------------- >< 


The IsAncestor method checks if an item is an ancestor of another item. 


Arguments: 


The arguments are: 


hParent 


The ancestor. 


hItem 


The item to be checked. 


Return value: 


1 if AParent is an ancestor of Atem. 


20.2. Notification Messages 


The tree view control sends notification messages to notify about events. For more information on 
notification messages, refer to ConnectListNotify. 


The following example shows how to connect the tree view notification messages with the corresponding 
message: 


: :method Init 
use arg InitStem. 
if Arg(1,"o") - 1 then 
InitRet - self^Init:super 
else 
InitRet = self^Init:super(InitStem.) 


if self^Load("tree.rc", ) \= O then do 
self^InitCode - 1 
return 
end 


/* Connect dialog control items to class methods */ 
self^ConnectTreeNotify("IDC TREE","SelChanging","OnSelChanging ПС TREE") 
self^ConnectTreeNotify("IDC, TREE", "SelChanged","OnSelChanged IDC, TREE") 
self^ConnectTreeNotify("IDC  TREE","Expanding","OnExpanding ПОС TREE") 
self^ConnectTreeNotify("IDC, TREE", "Expanded", "OnExpanded_IDC_TREE") 
self^ConnectTreeNotify("IDC, TREE", "DefaultEdit") 
self^ConnectTreeNotify("IDC, TREE","Delete","OnDelete IDC TREE") 
self^ConnectTreeNotify("IDC, TREE", "KeyDown" , "UÜnKeyDown, IDC, TREE") 
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self^ConnectButton("IDC PB NEW","IDC PB NEW") 
self^ConnectButton("IDC PB DELETE","IDC. PB DELETE") 
self^ConnectButton(2,"Cancel") 
self^ConnectButton(9,"Help") 
self^ConnectButton(1,"OK") 

return InitRet 
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A slider control, which is also called a trackbar, is a window that contains a slider and optional tick 
marks. When the user moves the slider, using either the mouse or the direction keys, the slider sends 
notification messages to indicate the change. 


Sliders are useful if you want the user to select a specific value or a set of consecutive values within a 
specific range. For example, you might use a slider to enable the user to set the repeat rate of the 
keyboard by moving the slider to a given tick mark. 


The slider in a trackbar moves in increments that you specify when you create it. For example, if you 
specify that the trackbar should have a range from 0 to 10, the slider can occupy only eleven positions: a 
position at the left side of the slider and one position for each increment in the range. Typically, each of 
these positions is identified by a tick mark. 


After you have created a slider, you can use the SliderControl methods to set and retrieve its properties. 
Refer to PROPDEMO.REX in the OODIALOG\SAMPLES directory for an example. 


The SliderControl class sends notification messages to notify about the event. For information about 
notification messages, refer to ConnectListNotify. 


Requires: 


The SliderControl class requires the class definition file oodwin32.cls: 


::requires "oodwin32.cls" 


Methods: 


Instances of the SliderControl class implement the methods listed in the SliderControl Instance 
Methods table. 


Table 21-1. SliderControl Instance Methods 


















































Method... ..оп page 
ClearSelRange ClearSelRange 
ClearTicks ClearTicks 
CountTicks CountTicks 
GetLineStep GetLineStep 
GetPageStep GetPageStep 
GetTick GetTick 
InitRange InitRange 
InitSelRange InitSelRange 
Pos Pos 

Pos= Pos= 

Range Range 
SelRange SelRange 
SetLineStep SetLineStep 
SetMax SetMax 
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Method... ..оп page 
SetMin SetMin 
SetPageStep SetPageStep 
setPos setPos 

SetSelEnd SetSelEnd 
SetSelStart SetSelStart 
SetTickAt SetTickAt 
SetTickFrequency SetTickFrequency 








21.1. Pos= 


»»-aSLliderControl"Pos---value---------------------------------- >< 


The Pos= method sets the new logical position of the slider and redraws the slider. 


Arguments: 


The only argument is: 


value 


The new logical position. A valid position is an integer value within the range of the minimum 
and maximum positions of the slider. If you specify a value outside this range, the position is 
set to the maximum or minimum position. 


21.2. setPos 


»»-aSliderControl^setPos(--pos--,--*---4--)-------------------- >< 


The setPos method sets the new logical position of the slider and redraws the slider if required. 


Arguments: 


The arguments are: 


pos 


The new logical position. A valid position is an integer value within the range of the minimum 
and maximum positions of the slider. If you specify a value outside this range, the position is 
set to the maximum or minimum position. 
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redraw 


The redraw flag. If you specify 1, the control is redrawn with the slider at the position given by 
pos. If you specify 0 or omit this argument, the control is not redrawn. However, the new 
position is set regardless of the redraw argument. 


Example: 


The following example sets the slider to the maximum position, with the range of the slider already 
been set to 0 to 100 using the setRange method: 


::method SetToMax 
ctrl-self^GetSliderControl("IDC 1") 
ctrl^setPos(100,1) 


21.3. Pos 


2»-aDl1derControl Ров-------- ----------- шо шу шышы шу >< 


The Pos method retrieves the current logical position of the slider. 


Return value: 


The current logical position of the slider. 


Example: 


The following example displays the current slider position: 


::method DisplayPos 
ctrl-self^GetSliderControl("IDC 1") 
pos = ctrl^Pos 
say pos 


21.4. InitHange 


+-0---+ +-100-+ +-0-+ 
»»-aSliderControl^InitRange(--4*-----4--,--4-----4--,--4---4--)-»« 
+-min-+ +-шах-+ +-1-+ 


The InitRange method sets Ше minimum and maximum positions of the slider and redraws the slider, if 
required. 
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Arguments: 


The arguments are: 
min 
The minimum position of the slider. The default is 0. 


max 


The maximum position of the slider. The default is 100. 


redraw 


The redraw flag. If you specify 1, the slider is redrawn after the range is set. If you specify 0 or 
omit this argument, the slider is not redrawn. 


Return value: 


0 
The range was set. 
-1 
The minimum you specified is greater than Ше maximum. 
Example: 


The following example sets the range, the line step, the page step, and the tick frequency of the 
slider: 


::method InitDialog 

curSL = self^GetSliderControl("IDC 1") 

if curSL \= .Nil then do 
curSL~ InitRange (0,100) 
curSL^SetLineStep(1) 
curSL^SetPageStep(10) 
curSL^SetTickFrequency (10) 

end 


21.5. SetMin 


+-1-+ 
»»-aSliderControl^SetMin(--min--,--4---4--)-------------------- >< 
+-0-+ 


The SetMin method sets the minimum logical position for a slider and redraws the slider, if required. 
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Arguments: 
The arguments are: 
min 
The minimum position of the slider. 


redraw 


The redraw flag. If you specify 1 or omit this argument, the slider is redrawn after the 
minimum position is set. If you specify 0, the slider is not redrawn. 


Return value: 


The minimum position was set. 


You omitted min. 


21.6. SetMax 


+-1-+ 
»»-aSliderControl^SetMax(--max--,--4*---4--)-------------------- >< 
+-0-+ 


The SetMax method sets the maximum logical position for a slider and redraws the slider, if required. 


Arguments: 


The arguments are: 
min 
The maximum position of the slider. 


redraw 


The redraw flag. If you specify 1 or omit this argument, the slider is redrawn after the 
maximum position is set. If you specify 0, the slider is not redrawn. 
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Return value: 


The maximum position was set successfully. 


You omitted min. 


21.7. Range 


»»-aSliderControl^Range---------------------------------------- >< 


The Range method retrieves the minimum and maximum positions of the slider. 


Return value: 


The minimum and maximum positions of the slider, separated by a blank. 


Example: 


The following example displays the range of a slider: 


::method DisplayRange 


ctrl-self^GetSlidercontrol("IDC 1") 


range - ctrl^Range 
parse var range min max 
say min max 


21.8. ClearTicks 


+-1-+ 
>>-aSliderControl~ClearTicks (--+---+ 
+-0-+ 


--) — ——MM 


-------------- >< 


The ClearTicks method removes Ше current tick marks from a slider. It does not, however, remove Ше 
first and last tick marks because they are created automatically by the slider. 
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Arguments: 


The arguments are: 


redraw 


The redraw flag. If you specify 1 or omit this argument, the slider is redrawn after the tick 
marks are removed. If you specify 0, the slider is not redrawn. 


Return value: 


0. 


21.9. CountTicks 


>>-а51дегСопъго! Count 1 ска------<-5н------- 5 ------------ >< 


The CountTicks method retrieves the number of tick marks in a slider, including the first and last tick 
marks, which are created automatically by the slider. 


Return value: 


The number of tick marks. 


21.10. GetTick 


»»-aSliderControl^GetTick(--tic--)----------------------------- >< 


The GetTick method retrieves the logical position of a tick mark in a slider. A valid position is an integer 
value within the minimum and maximum positions of the slider. 


Arguments: 
The only argument is: 
tic 


A zero-based index identifying a tick mark. A valid index is in the range of 0 to 2 ticks less 
than the tick count returned by the CountTicks method (see CountTicks). 


Return value: 


The logical position of the specified tick mark, or -1 if you did not specify a valid index for fic. 
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21.11. SetTickAt 


»»-aSliderControl^SetTickAt(--pos--)--------------------------- >< 


The SetTickAt method sets a tick mark at the specified logical position in the slider. 


Arguments: 


The only argument is: 


pos 


An integer value within the minimum and maximum positions of the slider. 


Return value: 


The tick mark was set. 
You omitted pos. 


For all other cases. 


21.12. SetTickFrequency 


+-1----+ 
>>-aSliderControl~SetTickFrequency (--+------ *--)--------------- >< 
+-freq-+ 


The SetTickFrequency method sets the interval frequency for tick marks in a slider. For example, if you 
set the frequency to 2, a tick mark is displayed for every other increment in the slider’s range. 


Arguments: 


The only argument is: 
freq 


The frequency of the tick marks. The default is 1, that is, every increment in the range is 


associated with a tick mark. 
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Return value: 


0 
The tick mark frequency was set. 
-1 
You omitted freq. 
1 
For all other cases. 
Example: 


The following example sets the range, the line step, the page step, and the tick frequency of the 
slider: 


::method InitDialog 

curSL = self^GetSliderControl("IDC 1") 

if curSL \= .Nil then do 
curSL~ InitRange (0,100) 
curSL^SetLineStep(1) 
curSL^SetPageStep(10) 
curSL^SetTickFrequency (10) 

end 


21.13. GetLineStep 


»»-aS8liderControl^GetLineStep---------------------------------- >< 


The GetLineStep method retrieves the number of logical positions that the slider moves in response to 
keyboard input from the arrow keys, such as the Right arrow or the Down arrow keys. The logical 
positions are the integer increments within the minimum and maximum positions of the slider. 


Return value: 


The line size for the slider. 


21.14. GetPageStep 


»»-aSliderControl^GetPageStep---------------------------------- >< 


The GetPageStep method retrieves the number of logical positions that the slider moves in response to 
keyboard input, such as the PageUp or PageDown keys, or mouse input, such as clicks in the slider’s 
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channel. The logical positions are the integer increments within the minimum and maximum positions of 
the slider. 


Return value: 


The page size for the slider. 


21.15. SetLineStep 


»»-aSliderControl^SetLineStep(--step--)------------------------ >< 


The SetLineStep method sets the number of logical positions that the slider moves in response to 
keyboard input from the arrow keys, such as the Right arrow or the Down arrow keys. The logical 
positions are the integer increments within the minimum and maximum positions of the slider. 


Arguments: 


The only argument is: 


step 


The new line size. 


Return value: 


The previous line size, or -1 if you omit step. 


Example: 


The following example sets the range, the line step, the page step, and the tick frequency of the 
slider: 


::method InitDialog 

curSL = self^GetSliderControl("IDC 1") 

if curSL \= .Nil then do 
curSL~ InitRange (0,100) 
curSL^SetLineStep(1) 
curSL^SetPageStep(10) 
curSL^SetTickFrequency (10) 

end 


21.16. SetPageStep 


»»-aS81iderControl^SetPageStep(--step--)------------------------ >< 


The SetPageStep method sets the number of logical positions that the slider moves in response to 
keyboard input, such as the PageUp or PageDown keys, or mouse input, such as clicks in the slider’s 
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channel. The logical positions are the integer increments within the minimum and maximum positions of 
the slider. 


Arguments: 


The only argument is: 


step 


The new page size. 


Return value: 


The previous page size. 


Example: 


The following example sets the range, the line step, the page step, and the tick frequency of the 
slider: 


::method InitDialog 

curSL = self^GetSliderControl("IDC 1") 

if curSL \= .Nil then do 
curSL~ InitRange (0,100) 
curSL^SetLineStep(1) 
curSL^SetPageStep(10) 
curSL^SetTickFrequency (10) 

end 


21.17. InitSelRange 


+-0---+ +-0------ + 
>>-aSliderControl~ InitSelRange (--+-----+--,--+-----+--,--+--------+--)->< 
+-min-+ +-шах-+ +-redraw-+ 


The InitSelRange method sets the starting and ending logical positions for the current selection range in 
a Slider. It is ignored if the slider does not have a selection range. 


Arguments: 


The arguments are: 
min 
The logical starting position of the selection range. The default is 0. 


max 


The logical ending position of the selection range. If you omit this argument, the maximum 
position of the slider’s range is assumed. 
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redraw 


The redraw flag. If you specify 1, the slider is redrawn after the selection range is set. If you 
specify 0 or omit this argument, the selection range is set but the slider is not redrawn. 


Return value: 


The minimum you specified is greater than the maximum. 


In all other cases. 


21.18. SetSelStart 


+-1------ + 


>>-aSliderControl~SetSelStart (--min-- , --+-------- +--)---------- >< 
+-redraw-+ 


The SetSelStart method sets the starting logical position for the current selection range in a slider. It is 
ignored if the slider does not have a selection range. 


Arguments: 


The arguments are: 


min 
The logical starting position of the selection range. 


redraw 


The redraw flag. If you specify 1 or omit this argument, the slider is redrawn after the starting 
position has been set. If you specify 0, the starting position is set but the slider is not redrawn. 


Return value: 


You omitted min. 


In all other cases. 
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21.19. SetSelEnd 


+-1------ + 


>>-aSliderControl~SetSelEnd (--max-- ,--+-------- +--)------------ >< 
+-redraw-+ 


The SetSelEnd method sets the logical ending position for the current selection range in a slider. It is 
ignored if the slider does not have a selection range. 


Arguments: 


The arguments are: 


min 
The logical ending position of the selection range. 


redraw 
The redraw flag. If you specify 1 or omit this argument, the slider is redrawn after the ending 


position has been set. If you specify 0, the ending position is set but the slider is not redrawn. 


Return value: 


You omitted max. 


In all other cases. 


21.20. ClearSelRange 


»»-aSliderControl^ClearSelRange(--redraw--)-------------------- >< 


The ClearSelRange method clears the current selection range in a slider. 


Arguments: 


The only argument is: 


redraw 


The redraw flag. If you specify 1, the slider is redrawn after the selection is cleared. 
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Return value: 


0. 


21.21. SelRange 


>>-aSliderControl~SelRange 


The SelRange method retrieves the starting position of the current selection range in a slider. 


Return value: 


The starting and ending positions of the current selection range, separated by a blank. 
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A progress bar is a control that an application can use to indicate the progress of a lengthy operation. It 
consists of a rectangle that is gradually filled, from left to right or from bottom to top, with the system 
highlight color as an operation progresses. It has a range and a current position. The range represents the 
entire duration of the operation, and the current position represents the progress that the application has 
made toward completing the operation. 


The underlying Windows progress bar control has been updated to allow a full 32-bit number to specify 
the minimum and maximum range and current position. Previously, the highest possible range or current 
position value wass 65,535. The range is now -2147483648 through 2147483647. 


Some sample programs included in the ooRexx distribution have examples of how to use the progress bar 
control. See for instance: oodPBar.rex and propDemo.rex in the samples\ooDialog directory. 


Requires: 
The ProgressBar class requires the class definition file oodWin32.cls: 


::requires "oodWin32.cls" 


Subclass of: 


The progress bar class is a subclass of the DialogControl class and therefore inherits all methods of 
that class. 


Mixin Class Inherits: 


The progress bar class inherits from the following mixin classes, (indirectly through the 
DialogControl class.) 


The WindowBase 


The WindowExtensions 


Instantiation: 


Use the getProgressBar() method to retrieve an object of the progress bar class. 


Dynamic Definition: 


To dynamically define a progress bar in a UserDialog class, use the addProgressBar() method. 


Event Notification 


The progress bar does not send notification messages. 


Syntax Errors: 


АП methods of the progress bar class will raise syntax errors if incorrect arguments are detected. 


Methods: 


Instances of the ProgressBar class implement the methods listed in the following table. 


Table 22-1. ProgressBar Instance Methods 
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Method... ...Description 
backgroundColor backgroundColor 
barColor barColor 
getPos getPos 
getRange getRange 
setMarquee setMarquee 
setPos setPos 
setRange setRange 
setStep setStep 
step step 

22.1. step 

»»--step(--4----------- 4--)--------------------- >< 


+-increment-+ 


The step method advances the current position of the progress bar. If increment is specified, the current 
position is incremented by that amount. If not specified, the current position is incremented by the 
amount set with the setStep() method. The progress bar is redrawn to reflect the new position. 


There is this important difference between using an increment, usually called a delta, and stepping by the 
amount specified in the setStep() method. When an increment is used and the increment would position 
the the progress bar past its maximum range, the progress bar is advanced to the end and stays there. 


On the other hand, when the default step is used and the progress bar reaches the end of its range, it is 


reset to the minimum. 


Details 


Raises syntax errors when incorrect arguments are detected. 


Arguments: 


The single optional argument is the amount to advance the current position. If this argument is not 
used, the position is advanced by the value set with the setStep method. 


Return value: 


The previous position. 


22.2. setPos 


»»--setPos(--newPos--)-------------------------- >< 
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The setPos method sets the new position for a progress bar and redraws the bar to reflect the new 
position. 


Details 


Raises syntax errors when incorrect arguments are detected. 


Arguments: 


The single required argument is the new position for the progress bar. 


Return value: 


The previous position is returned. 


22.3. getPos 


22 -рвъРроз------- a aa a АЯ >< 


This method returns the current position of the progress bar. 


Details 


Raises syntax errors when incorrect arguments are detected. 


Arguments: 


There are no arguments. 


Return value: 


The current position of the progress bar is retunred. 


Example: 


In this example, the range for the progress bar is set to -200 to 200. At another point in the program, 
the current position is printed to the screen. This is not real-world use case, just an example: 


pb = self~getProgressBar ("IDC_PB_COUNTDOWN") 
if pb \= .Nil then do 

pb” setRange (-200, 200) 

pb^setStep(10) 

pb^setPos(-200) 
end 


::method display private 
expose pb 


pb^step 
say ’Now at position’ pb^getPos 


/* Output might be: 
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Now at position -190 
Now at position -180 
Now at position -170 
Now at position -160 
*/ 
22.4. setStep 
»»--setStep(--4--------- 4--)-------------------- >< 


*-newstep-*t 


This method specifies the step increment for the progress bar. The step increment is the amount by which 
the progress bar advances its current position when the step() method is called without an increment 


value. 


By default, the underlying progress bar uses a default step of 10. It is not neccessary to set the step at all 
if 10 is satisfactory. 


Details 


Raises syntax errors when incorrect arguments are detected. 


Arguments: 


The single optional argument is the new step increment. The default step increment is 10. 


Return value: 


This method returns the previous step increment. 


22.5. setRange 


The setRange method sets the minimum and maximum values for the progress bar. The minimum and 
maximum values are signed numbers. To use the entire range possible the programmer would use 
-2147483648 through 2147483647 for the minimum and maximum. 


Details 


Raises syntax errors when incorrect arguments are detected. 
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Arguments: 


The arguments are: 


min 
Optional. The minimum range value. The default is 0. 


max 


Opitonal. The maximum range value. The default is 100. 


Return value: 


A string containing the minimum and maximum value of the previous range, separated by a blank. 
The first word in the string is the old minimum and the second word is th old maximum. 


Note that the underlying progress bar does not return the full 32-bit value of the range. It returns the 
range within the old limit of 0 through 65535. If the programmer is using a range outside those 
values, the returned previous value here will not be correct. To retrieve the correct 32-bit values, use 
the getRange() method 


22.6. getRange 
>>--ргеНапре--------------------------<-------- >< 
Retrives Ше current high and low limits of Ше range of Ше progress bar. 
Details 
Raises syntax errors when incorrect arguments are detected. 


Arguments: 


There are no arguments to this method. 


Return value: 


The range is returned in a .Directory object with the following indexes: 


min 
The current minimum limit, as a signed number, for the progress bar. 


max 


The current maximum limit, as a signed number, for the progress bar. 


Example: 
This example demonstrates how the range is returned: 


pb = self~getProgressBar ("IDC_PB_COUNTDOWN") 
if pb \= .Nil then do 
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pb” setRange (-200 , 200) 
pb^setStep(10) 
pb^setPos(-200) 

end 


::method displayCurrentRange private 
expose pb 


range = pb^getRange 

say ?'Current minimum: range^min ’current maximum:? гапре шах 

say 

say ’Current minimum: pb^getRange^min ’current maximum: pb^getRange^max 


/* Output would be: 
Current minimum: -200 current maximum: 200 
Current minimum: -200 current maximum: 200 


*/ 


22.7. setMarquee 


»»--setMarquee(--4------ *--—----------- *--)----- >< 
*--on--* +--,-pause--+ 


Sets the progress bar to marquee mode. This causes the progress bar to move in a scrolling manner. Use 
this method when you do not know the amount of progress toward completion but wish to indicate that 
progress is being made. 


This method is used to start or stop the scrolling. Note that the progress bar has to have the 
PBS_MARQUEE style. When using the addProgressBar() method in a UserDialog class the style 
keyword is MARQUEE. Otherwise, a resource editor will handle adding the PBS_MARQUEE style flag 
to the resource script. 


Each time the marquee mode is turned on, the progress bar is reset to the minimum of its range. 


Details 


This method requires Common Control Library version 6.0 or later. If necessary use the 
comCtl32Version() method to determine the current version of the library. 


Raises syntax errors when incorrect arguments are detected. 


Requires the progress bar to have the PBS MARQUEE style. 
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Arguments: 


The arguments are: 


on 
Optional. True or false. True to start the marquee, false to stop it. The default is true to start the 
marquee. 

pause 


Optional. The time in milliseconds between the animation. The default is 1000 (one second.) 


Return value: 


This method always returns . true. 


Example: 
This example turns marquee mode on and sets the time between updates at one half of a second: 


pb = self~getProgressBar ("IDC_PB_SEARCHING") 
if pb \== .nil then pb^setMarquee(.true, 500) 


22.8. barColor 


»»--barColor(--colorRef--)-------------------------------------- >< 


Sets the color of the progress indicator bar in the progress bar control. 


Details 
This method is only effective in the Windows Classic theme. 


Raises syntax errors when incorrect arguments are detected. 


Arguments: 


The required argument is: 


colorRef 


А COLORREF that specifies the new color for the bar in the progress bar, or CLR. DEFAULT 
to set the bar color back to its default color. If needed, use the colorRef() method of the Image 
class to construct the proper value for this argument. 


Return value: 


This method returns the previous bar color, or CLR. DEFAULT if the progress bar was using the 
default color. 
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Example: 


This example sets the bar color to a custom color. This will only have effect in Windows Classic 
theme. It is not neccessary to set numeric digits to 11 to use this method. In the example this is only 
done to allow the return to be displayed in hexadecimal. 


numeric digits 11 

progressBar = self~getProgressBar ("IDC_PB_CONNECTING") 

say ’Going to set the bar color for the progress bar’ 

ret = progressBar~barColor(.Image~colorRef (180, 255, 110)) 
say 2014 bar color was: > ret ’(Ox’ret~d2x’)’ 


/* Output might be: 


Going to set the bar color for the progress bar 
Old bar color was: 4278190080 (OxFF000000) 


*/ 


22.9. backgroundColor 


»»--backgroundColor(--colorRef--)-------------------------------------- >< 


Sets the background color in the progress bar. 


Details 
This method is only effective in the Windows Classic theme. 


Raises syntax errors when incorrect arguments are detected. 


Arguments: 


The required argument is: 


colorRef 


A COLORREF that specifies the new background color for the progress bar, or 
CLR, DEFAULT to set the backgroun color back to its default color. If needed, use the 
colorRef() method of the Image class to construct the proper value for this argument. 


Return value: 


This method returns the previous background color, or CLR. DEFAULT if the progress bar was 
using the default color. 
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Example: 


This example sets the background color to a custom color. This will only have effect in Windows 
Classic theme. It is not neccessary to set numeric digits to 11 to use this method. In the example this 
is only done to allow the return to be displayed in hexadecimal. 


numeric digits 11 

progressBar = self~getProgressBar ("IDC_PB_CONNECTING") 

say ’Going to set the background color for the progress bar’ 
ret = progressBar~backgroundColor(.Image~colorRef(55, 111, 18)) 
say 01а background color was:? ret ’(Ox’ret~d2x’)’ 


/* Output might be: 


Going to set the background color for the progress bar 
Old background color was: 4278190080 (OxFF000000) 


*/ 
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A tab control can be compared to a divider in a notebook or a label in a file cabinet. By using a tab 
control, an application can define several pages for the same area of a dialog or dialog control. Each page 
consists of a set of information or a group of controls that the application displays when the user selects 


the corresponding tab. 


A special type of tab control displays tabs that look like buttons. Clicking a button immediately performs 
a command instead of displaying a page. 


You can apply specific characteristics to tab controls by specifying tab control styles. For example, you 


can specify the alignment and general appearance of the tabs in a tab control. 


By default, a tab control displays only one row of tabs. If not all tabs can be shown at once, the tab 
control displays an up-and-down control so that the user can scroll to view additional tabs. 


Refer to PROPDEMO.REX in the OODIALOG\SAMPLES directory for an example. 


The TabControl class sends notification messages to notify about the event. For information about 
notification messages, refer to ConnectListNotify. 


Requires: 


The TabControl class requires the class definition file oodwin32.c1s: 


::requires "oodwin32.cls" 


Methods: 


Instances of the TabControl class implement the methods listed in the TabControl Instance Methods 


table. 


Table 23-1. TabControl Instance Methods 





















































Method... ..оп page 
AddFullSeq AddFullSeq 
AddSequence AddSequence 
AdjustToRectangle AdjustToRectangle 
Delete Delete 
DeleteAll DeleteAll 
Focus Focus 
Focused Focused 
getImageList getImageList 
Insert Insert 
ItemInfo ItemInfo 
Items Items 

Last Last 

Modify Modify 
PosRectangle PosRectangle 
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Method... ..оп page 
Removelmages (deprecated) Removelmages (deprecated) 
Required WindowSize Required WindowSize 
Rows Rows 

Select Select 

SelectIndex SelectIndex 

Selected Selected 

SelectedIndex SelectedIndex 
setImageList setImageList 

SetImages (deprecated) SetImages (deprecated) 
SetPadding SetPadding 

SetSize SetSize 











23.1. Insert 


>>-aTabControl~ Insert (--+-----+-- ,--text-- ,--icon-- ,--numValue--) ->< 
+-tab-+ 


The Insert method inserts a new tab in a tab control. 


Arguments: 


The arguments are: 


tab 


The number of the tab. If you omit this argument, the number of the last tab is increased by 1, 
starting with 0. 


text 


The label text for the inserted tab. 
icon 

The index of the icon in the image list of the tab control, set with the setImageList() method. 
num Value 


An integer value stored together with the tab to save information. 


Return value: 


The number of the new tab, or -1 for all other cases. 
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Example: 
The following example inserts three tabs in a tab control with the specified text and a specific item: 


::method InitDialog 
InitDlgRet = self~InitDialog: super 
curTab = self~GetTabControl ("10 ТАВ") 
if curTab \= .Nil then do 
curTab~setImageList (imageList) 
curTab^Insert(," First Tab",0) 
curTab^Insert(,"Second Tab",1) 
curTab^Insert(," Third Tab",2) 
end 
return InitDlgRet 


23.2. Modify 


»»-aTabControl^Modify (--tab--,--text--,--icon--,--numValue--)--»« 


The Modify method sets some or all of the attributes of a tab. 


Arguments: 


The arguments are: 


tab 


The number of the tab. 


text 


The label text for the tab. 


icon 


The index of the icon in the image list of the tab control, set with the setImageList() method. 


numValue 


An integer value stored together with the tab to save information. 


Return value: 


The attributes were set. 


You did not specify tab. 
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In all other cases. 


23.3. AddSequence 


>>-aTabControl~AddSequence(--text1-- ,--text2-- ,--text3--,--...--)->< 


The AddSequence method inserts a sequence of tabs in a tab control for which you can only specify the 
label text. The number of the tab inserted last is increased by 1. 


Arguments: 


The only argument is: 


text 


The label text for the inserted tab. 


Return value: 


The number of the tab inserted last, or -1 for all other cases. 


Example: 


The following example inserts three tabs in a tab control: 


::method InitDialog 
InitDlgRet = self~InitDialog: super 
curTab = self~GetTabControl ("10 ТАВ") 
if curTab \= .Nil then do 
curTab~AddSequence("First Tab","Second Tab","Third Tab") 
end 
return InitDlgRet 


23.4. AddFullSeq 


»»-aTabControl^AddFullSeq(--text 1--,--icon 1--,--numValue 1--,--text 2--> 


»--,--icon, 2--,--nunValue, 2--,--...--)---------------------------------- >< 


The AddFullSeq method inserts a sequence of tabs in a tab control for which you can specify the 
number, label text, and integer value. 
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Arguments: 


The arguments are: 


text 
The label text for the inserted tab. 
icon 


The index of the icon in the image list of the tab control, set with the setImageList() method. 


numValue 


An integer value stored together with the tab to save information. 


Return value: 
The number of the tab inserted last, or -1 for all other cases. 


Example: 


The following example adds a sequence of tabs and sets their text and icon: 
::method InitDialog 

InitDlgRet = self~InitDialog: super 

curTab = self~GetTabControl ("10 ТАВ") 

if curTab \= .Nil then do 


curTab~setImageList (imageList) 


curTab^AddFullSeq("sii", 0, , "512", 1, , "s13", 2, , "s14", 3) 
end 
return InitDlgRet 
23.5. Items 
22-8TabControl" Ttems---—————------——————-—e eoe nece et >< 


The Items method retrieves the number of tabs in a tab control. 


Return value: 
The number of the tabs, or О for all other cases. 
Example: 


The following example displays the number of tabs: 


::method DisplayTabNum 
curTab = self^GetTabControl("ID. TAB") 
if curTab Ае .Nil then do 


say curTab^Items 
end 
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23.6. Rows 


>>=alabControl Rows + i343 42 SSS SSSR Seas шз ыр ысын SaaS SSeS >< 


The Rows method retrieves the current number of rows of tabs in a tab control. Only tab controls with 
multiline style can have several rows of tabs. 


Return value: 


The number of the tab rows. 


23.7. ItemInfo 


»»-aTabControl^ItemInfo(--tab--)------------------------------- >< 


The ItemInfo method retrieves information about a tab in a tab control. 


Arguments: 


The only argument is: 


text 


The number of the tab. 


Return value: 


A compound variable that stores the attributes of the tab, or -1 in all other cases. The compound 
variable can be: 


RetStem.'TEXT 
The label text for the tab. 


RetStem.' IMAGE 


The index of the tab in the image list of the tab control, or -1 if the tab does not have an image. 


RetStem.'PARAM 


An integer value stored together with the tab to save information: 


Example: 
The following example displays the text of all tabs: 


::method DisplayText 
curTab = self^GetTabControl("ID. TAB") 
if curTab \= .Nil then do 
do i = 0 to curTab^Items - 1 
ItemInfo. = curTab^ItemInfo(i) 
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say ItemInfo. !Text 
end 
end 


23.8. Delete 


»»-aTabControl^Delete(--tab--)--------------------------------- >< 


The Delete method removes a tab from a tab control. 


Arguments: 


The only argument is: 


tab 


The number of the tab to be removed. 


Return value: 


The tab was removed. 
You did not specify tab or there is no tab available. 


For all other cases. 


23.9. DeleteAll 


»»-aTabControl^DeleteAll--------------------------------------- >< 


The DeleteAll method removes all tabs from a tab control. 


Return value: 


The tabs were removed. 
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1 


For all other cases. 


23.10. Last 


>2-аТаБбош го! Lasts t sss тт еее SaaS Se >< 


The Last method retrieves the number of the last tab in a tab control. 


Return value: 


The number of the last tab, or 0 in all other cases. 


23.11. Selected 


>>-aTabControl”~ 8е1есіеа---------------------------------------- >< 


The Selected method retrieves the label text of the currently selected tab. 


Return value: 


The label text of the currently selected tab, or 0 in all other cases. 


23.12. Selectedindex 


»»-aTabControl^SelectedIndex----------------------------------- >< 


The SelectedIndex method retrieves the number of the currently selected tab. 


Return value: 


The number of the currently selected tab, or 0 in all other cases. 


23.13. Select 


»»-aTabControl^Select(--text--)-------------------------------- >< 


The Select method selects the tab with the specified label text. 
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Arguments: 


The only argument is: 


text 


The label text of the tab to be selected. 


Return value: 


The number of the selected tab, or O in all other cases. 


23.14. Selectindex 


»»-aTabControl^SelectIndex(--tab--)---------------------------- >< 


The SelectIndex method selects the specified tab in a tab control. 


Arguments: 


The only argument is: 


tab 


The number of the tab to be selected. 


Return value: 


The number of the previously selected tab, or -1 in all other cases. 


23.15. Focus 


»»-aTabControl^Focus(--tab--)---------------------------------- >< 


The Focus method sets the focus to the specified tab in a tab control. 


Arguments: 


The only argument is: 


tab 


The number of the tab to receive the focus. 
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Return value: 


0. 


23.16. Focused 


22-aTabControl Focused----—-----------------4-ncoocecceo eee шы >< 


The Focused method returns the number of the tab that has the focus. The tab with the focus can differ 
from the selected tab. 


Return value: 


The number of the tab having the focus. 


23.17. setimageList 


»»--setlmageList(--newImageList--)--------------------------------------------- >< 


Assigns, or removes, an image list for the tab control. Using .ni1 for the first argument removes the 
current image list. Each tab can have an icon associated with it, which is specified by an index in the 
image list for the tab control. 


Destroying a tab control does not destroy an image list that is associated with it. The programmer must 
destroy the image list separately, if desired. This is useful if the programmer wants to assign the same 
image list to multiple tab controls. In essence, the ownership of the image list remains with the 
programmer. The ImageList and Image classes are used to manage image lists and images in ooDialog. 
The documentation on both classes discusses when and why the programmer may want to release image 
lists. The Image class documentation has the most detail on this subject. 


Details 
Raises syntax errors when incorrect arguments are detected. 
Arguments: 


The single required argument is 


newImageList 


The image list to assign to the tab control. If this argument is .nil the existing image list, if 
any, is removed. 


Return value: 


The existing image list is returned, if there is one. Otherwise, .nil is returned. 
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Example: 


This example creates an image list from a bitmap file that is a series of 16x16 bitmaps, each one a 
colored letter. The image list is then assigned to the tab control. 


-- Add all the tabs, including the index into the image list for an icon for 
-- each tab. 


tc^AddFullSeq("Red", O, ,"Green", 1, , "Moss", 2, 
"Cyan", 5, я "Gray", 6) 


‚ "Blue", 3, , "Purple", 4, , - 


-- Create a COLORREF (pure white) and load our bitmap. The bitmap is a 
-- series of 16x16 images, each one a colored letter. 

cRef = .Image~colorRef(255, 255, 255) 

image = .Image~getImage("bmp\psdemoTab. bmp") 


-- Create our image list, as a masked image list. 
flags = .DlgUtil^or(.Image^toID(ILC COLOR24), .Image^toID(ILC MASK)) 
imageList = .ImageList^create(.Size^new(16, 16), flags, 10, 0) 


if Mimage^isNull, \imageList~isNull then до 
imageList~addMasked(image, cRef) 
tc~setImageList (imageList) 


-- The image list makes a copy of each image added to it. So, we can now 
-- release the original image to free up some small amount of system 
-- resoureces. 


image^release 


end 
else do 

-- do some type of error handling 
end 


23.18. getlmageList 


>>-—pet Imagelist 9s Ss ss SSS SS SSS ast Saas nee == >< 


Retrieves the current image list from the tab control, if there is one. 


Arguments: 


There are no arguments to this method. 


Return value: 
This method returns the current image list, if there is one. .nil is returned if there is no current 
image list. 

Example: 


This example gets the current image list from the tab control when the dialog is closed and releases 
it as it is no longer userd. 


::method ok 
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self^releaseImageLists 
return self^ok:super 


::method cancel 
self^releaseImageLists 


return self^cancel:super 


::method releaseImageLists 
expose tabControl 


imageList = tabControl~getImageList 
if imageList \== .nil then imageList~release 


23.19. setlmages (deprecated) 


Note: This method is deprecated. It is replaced by the functionally equivalent setlmageList() method. 
Do not use this method in new code. Try to migrate existing code to to the setImageList O method. 
This method may not exist in future versions of ooDialog. 


23.20. removelmages (deprecated) 


Note: This method is deprecated. It is replaced by the functionally equivalent setlmageList() method. 
Do not use this method in new code. Try to migrate existing code to to the setImageList() method. 
This method may not exist in future versions of ooDialog. 


23.21. SetPadding 


»»-aTabControl^SetPadding(--padX--,--padY--)------------------- >< 


The SetPadding method sets the amount of space (padding) around the icon and the label of a tab. 


Arguments: 


The arguments are: 


padX 


The amount of horizontal padding, in pixels. 
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padY 


The amount of vertical padding, in pixels. 


Return value: 


0. 


23.22. SetSize 


»»-aTabControl^SetSize(--width--,--height--)------------------- >< 


The SetSize method sets the width and height of tabs in a fixed-width or owner-drawn tab control. 


Arguments: 


The arguments are: 


width 


The new width, in pixels. 


height 


The new height, in pixels. 


Return value: 


The old width and height as a string, in pixels. 


23.23. PosRectangle 


»»-aTabControl^PosRectangle(--tab--)--------------------------- >< 


The PosRectangle method retrieves the rectangle around a tab in a tab control. 


Arguments: 


The only argument is: 


tab 


The number of the tab. 
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Return value: 


A string containing the coordinates of the rectangle, or an empty string. The coordinates are 
separated by blanks and are in the following order: 


* X-coordinate of the upper left corner of the rectangle 
• Y-coordinate of the upper left corner of the rectangle 
* X-coordinate of the lower right corner of the rectangle 


• Y-coordinate of the lower right corner of the rectangle 


23.24. AdjustToRectangle 


»»-aTabControl^AdjustToRectangle(--left--,--top--,--right--,--bottom--)-»« 


The AdjustToRectangle method calculates the window rectangle of a tab control that corresponds to the 
specified display rectangle. 


Arguments: 


The arguments are: 


left 


The x-coordinate of the upper left corner of the display rectangle. 
top 

The y-coordinate of the upper left corner of the display rectangle. 
right 

The x-coordinate of the lower right corner of the display rectangle. 


bottom 


The y-coordinate of the lower right corner of the display rectangle. 


Return value: 


A string containing the coordinates of the window rectangle, or an empty string. The coordinates 
are separated by blanks and are in the following order: 


* X-coordinate of the upper left corner of the rectangle 
• Y-coordinate of the upper left corner of the rectangle 
* X-coordinate of the lower right corner of the rectangle 


• Y-coordinate of the lower right corner of the rectangle 
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23.25. RequiredWindowSize 


»»-aTabControl^RequiredWindowSize(--left--,--top--,--right--,--bottom--)-»« 


The RequiredWindowSize method calculates the display rectangle of a tab control that corresponds to 
the specified window rectangle. 


Arguments: 


The arguments are: 


left 


The x-coordinate of the upper left corner of the window rectangle. 


top 

The y-coordinate of the upper left corner of the window rectangle. 
right 

The x-coordinate of the lower right corner of the window rectangle. 


bottom 


The y-coordinate of the lower right corner of the window rectangle. 


Return value: 


A string containing the coordinates of the display rectangle, or an empty string. The coordinates are 
separated by blanks and are in the following order: 


* X-coordinate of the upper left corner of the rectangle 
• Y-coordinate of the upper left corner of the rectangle 
* X-coordinate of the lower right corner of the rectangle 


• Y-coordinate of the lower right corner of the rectangle 
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The PropertySheet class provides methods to control a property sheet. It is a subclass of the 
CategoryDialog class (see CategoryDialog Class). A property sheet is similar to a category dialog that 
spreads its dialog items over several pages (categories), where the individual pages are controlled by a 
tab control instead of radio buttons or combo box lists. 


Refer to PROPDEMO.REX in the OODIALOG\SAMPLES directory for an example. 


The PropertySheet class requires the class definition file oodwin32.cls: 
::requires "oodwin32.cls" 


Use an object of the DialogControl class or one of its subclasses to work with an individual dialog item 
of the sheets. To retrieve such an object, you can call one of the following methods depending on the 
requested control: 


* GetStaticControl 
* GetEditControl 
* GetButtonControl 
* GetRadioControl 
* GetCheckControl 
* GetListBox 

* GetComboBox 
* GetScrollBar 

* GetTreeControl 
* GetListControl 
* getProgressBar 
* GetSliderControl 
* GetTabControl 


24.1. Init 


+-10---+ 
»»-aPropertySheet^Init(--4---------- iia o Hes safes ф==,==> 
+-DlgData.-+ +-cattable-+ +-tabx-+ 
+-4----+ 
>--+------ 4--,--4------- 4--,--4------- +---)---------------------------- >< 
+-taby-+ +-style-+ +-hFile-+ 


The Init method is called when a new instance of the PropertySheet class is created and initializes the 
property sheet object. 
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Arguments: 


The arguments are: 


DlgData. 


An optional stem variable containing the initial values for some or all dialog items. If the 
dialog is terminated with the OK button, the values in the data fields of the dialog are copied to 
this variable. The ID of the dialog items is used to name the entry within the stem. 


cattable 


You can use this argument to set the category names, separated by blanks. Your class, which is 
a subclass of PropertySheet, must provide a method for each of the categories in the string to 
define the dialog items of the related category page. The name of the method is equal to the 
category name in the string. 


If you omit this argument, set the category names to the catalog directory in the InitCategories 
method (see InitCategories). 
tabx, taby 


The position of the tab control that is used to select the category. The default is 10,4. 


style 


Determines the style of the property sheet and the tab control used to select the visible 
category. The style must be specified as a text string that can contain tab control options (see 
AddTabControl) or the option WIZARD, which adds a backward and a forward button with ID 
11 and 12 to the dialog to switch between the category pages. 


hFile 


The file name of a header file containing symbolic ID defines for resources. 


Example: 
The following example creates a property sheet dialog with 4 sheets: 


dlg = MyProperty~new(MyData.,"Movies Cinemas Days Ticket", , ,"WIZARD") 
dlg^createCenter(200,180,"Let's go to the movies") 
dlg^execute("SHOWTOP") 


::class MyProperty subclass PropertySheet 
::method Movies /* define the Movies page */ 
::method Cinemas /* define the Cinemas page */ 


An additional example can be found under the Init method, in the BaseDialog section. This 
example shows the use of the dialog data stem and header file arguments in more detail. 
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In the Windows OS, a resource, is binary data used by a Windows-based application. Usually, the binary 
data is attached to one of the application’s executable files (*.exe or *.dll.) However, the binary data can 
also be generated dynamically in memory. (Which is common in ooDialog, for example the dialog 
template for a UserDialog is generated in memory.) 


The data in standard resources describes things familar to ooDialog programmers like, dialog boxes, 
icons, menus, cursors, bitmaps, fonts, etc. The standard resources also include accelerator tables, 
string-table entries, message-table entries, and other resourcess that ooDialog does not currently have 
support for, but may support in the future. 


This chapter describes ooDialog classes that provide access to Windows resources. The classes allow the 
oodialog programmer to use and manipulate resources in their ooDialog programs. This is an area of 
ooDialog that is slated for future improvements. The classes listed in the following table are documented 
in this chapter: 


Table 25-1. ooDialog Resource Classes 























Class Link to Description 
Image Image Class 
ImageList ImageList Class 
ResourceImage ResourceImage Class 





25.1. Image Class 


The Image class is used to work with and manipulate images. Currently, the image types supported 
include bitmaps, icons, cursors (cusors are a type of icon,) and enhanced metafiles. The enhanced 
metafile support is very limited at this time. 


The class supports loading images from files, from resources contained in any executable files (*.exe and 
* dll.) from the files associated with the ooDialog program, and from the generally available system 
resources. 


Note: The .Image class is the future direction that ooDialog will take for working with images, 
including bitmaps. This is a more flexible approach than the older bitmap methods used when 
ooDialog was first developed. It will allow access to more of the modern features of the Windows 
user interface than the older approach does. The older bitmap methods were designed to work with 
Windows 3.1 and have a number of limitations. The ooDialog programmer is strongly encouraged to 
migrate her code towards the .Image class. The older bitmap methods should be considered 
depracated, to a degree. Unfortunately, replacement methods for all of the older bitmap methods 
have not as yet been implmented. So, the older methods may still be necessary for some situations. 


A loaded image takes up some small part of the systems's resources. It is common to release an image 
when the programmer is done with it. The .Image class has the release() method to allow the programmer 
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to release the image, if desired. It is important to note that when the ooDialog program ends, that is 
when the ooRexx interpreter process ends, the Windows operating system cleans up all the system 
resources associated with any images used in the ooDialog program. Not releasing images does no harm 
and the ooDialog programmer should not be unduly worried about this aspect of images. 


In addition, when images are loaded as shared, the operating system completely manages them. Shared 
images should not be released. The .Image class tracks which images are loaded as shared and will not 
call the underlying API to release a shared image. So, again, the ooDialog programmer does not need to 
worry about mistakenly releasing a shared image. Once an image is released, it is no longer valid and the 
object can not be used as an argument to methods requiring a valid image. This applies to shared images 
also, even though they are not actually released. 


Why then would the ooDialog programmer want to release images? The main reason would be to 
minimize the memory footprint of an application. In a normal ooDialog program, with five to ten images, 
releasing the images would have no noticeable impact on the memory footprint. However, in a long 
running Rexx program that opened and closed a lot of dialogs that used images, releasing the images as 
the dialogs were closed would make a difference in the long run. The operating system would not clean 
up the resources used by the images until the main Rexx program ended. If the main program ran for 
days, or maybe was never intended to be shut down, it would make sense to release images that were no 


longer needed. 


Requires: 


The Image class requires the class definition file ooDialog.cls: 


::requires "ooDialog" 


Methods: 


Instances of the Image class implement the methods listed in the following table: 


Table 25-2. Methods of the .Image Class 


















































Method... ... description 
colorRef (Class method) colorRef 
fromFiles (Class method) fromFiles 
fromIDs (Class method) fromIDs 

getB Value (Class method) getB Value 
getGValue (Class method) getGValue 
getImage (Class method) getImage 
getRValue (Class method) getRValue 

toID (Class method) toID 

new (Class method) new 

handle handle 

isNull isNull 

release release 
systemErrorCode systemErrorCode 
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25.1.1. new (Class method) 


The Image class does not allow new Image objects to be instantiated from Rexx code using the new() 
method. New Image objects are obtained through one of the other Image class methods, or they are 
returned from methods of other classes. 


These methods are used to create new Image object(s). 


Image (class) method: getImage() 

Image (class) method: fromFiles() 

Image (class) method: fromIDs() 
ResourceImage (instance) method: getImage() 
ResourceImage (instance) method: getImages() 


25.1.2. tolD (Class method) 


»»--toID(--symbolicName--)----------------------------------------- >< 


The toID method is used to translate a symbolic name to its integer value. In general the symbolic name 
is related to images or color. Many of the arguments to the methods of classes related to images use the 
integer value of a symbolic ID in the Windows API. This method allows the programmer to use the 
symbolic ID without knowing what the actual integer value is. 


Take for example the task of retrieving the ’Question’ icon resource from the system using the 
getImage() method. The ooDialog programmer could either use the numerical value of 32514 or use the 
toID method as follows. Note that the two invocations of getImage() are equivalent: 


qIcon = .Image^getImage(.Image^toID(IDI QUESTION)) 


аТсоп = .Image~ getImage (32514) 


The symbolic ID keywords are spelled exactly as Microsoft spells them in the MSDN library which 
allows the ooDialog to easily look up the meaning of any single ID while at the same time reducing the 
documentation task for the ooDialog developers. The keywords are case sensitive and must be all in 


upper-case. 


Arguments: 


The single required argument is: 


symbolicName 


The symbolic name whose numeric value is desired. There any number of symbolic names and 
they are not listed here. Rather the symbolic names are listed in the documentation for the 
methods they are applicable to. 
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Return value: 


The return value is the numeric value of the symbol. 


Example: 


say ’The numeric value of the IDI_WINLOGO symbol is:’ „аре toID(IDI_WINLOGO) 
/* 


Output on the console would be: 


The numeric value of the IDI_WINLOGO symbol is: 32517 
*/ 


25.1.3. getImage (Class method) 


>>--get Image (--id--+-------- +--+-------- +--+--------- +--)----- >< 
+-,-type-+ +-,-size-+ +-,-flags-+ 


Instantiates a new .Image object from either an image file or from one of the system images. When id is a 
number then the corresponding system image is used. Otherwise, id is taken to be the name of an image 
file. File names can be either relative or absolute. 


Details 
Sets the .SystemErrorCode variable. 
Raises syntax errors when incorrect arguments are detected. 
Provides an interface to the Win32 API: LoadImage O. Use the MSDN library documentation to get 


more information on the arguments to this method. 


Arguments: 


If not a number, then id must be the name of a stand-alone image file. 


If id is a number than it is taken to be the resource id of an image provided by the system. The 
following are the symbolic names for all the system images. You can use .Image~toID() to get 
the correct numeric value for any of the following symbols: 


IDI APPLICATION OCR NORMAL OBM CLOSE OBM RGARROWD 

IDI HAND OCR IBEAM OBM UPARROW OBM_LFARROWD 

IDI QUESTION ОСК WAIT OBM DNARROW ОВМ MNARROW 

IDI EXCLAMATION ОСК CROSS OBM RGARROW | OBM COMBO 

IDI ASTERISK OCR UP OBM LFARROW OBM_UPARROWI 

IDI WINLOGO ОСК SIZENWSE OBM REDUCE OBM_DNARROWI 
OCR_SIZENESW OBM_ZOOM OBM_RGARROWI 
OCR_SIZEWE OBM_RESTORE OBM_LFARROWI 
OCR_SIZENS OBM_REDUCED OBM_SIZE 
OCR_SIZEALL OBM_ZOOMD OBM_BTSIZE 
OCR_NO OBM RESTORED  OBM CHECK 
OCR HAND OBM UPARROWD OBM_CHECKBOXES 
OCR_APPSTARTING OBM DNARROWD OBM BTNCORNERS 
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type 


Specifies the type of the image: bitmap, icon, or cursor. You can use .[mage-toID() to get the 
correct numeric value for one of the following symbols: 


IMAGE BITMAP IMAGE ICON 
IMAGE CURSOR 


The default is IMAGE BITMAP. 
size 
A .Size object that specifies the size of the image. 


The default is a size of 0x0. Under most circumstances this indicates that the actual size of the 


image should be used. However, the MSDN library documentation should be consulted for 
other meanings. 


flags 


The load resource flags for the LoadImage() API. The flags are one or more of the following 
symbols. You can use .Image-toID() to get the correct numeric value for any of the following 


symbols. The or method of the .DIgUtil class can be used to combine more than one of the 
symbols if needed. 


ГК DEFAULTCOLOR ТК CREATEDIBSECTION 
ГК DEFAULTSIZE LR_LOADFROMFILE 

LR LOADMAP3DCOLORS LR LOADTRANSPARENT 
LR MONOCHROMEB LR SHARED 


ГК VGACOLOR 


When id specifies a file name, the default flags are ГК LOADFROMFILE, othewise the 


default flags are ГК SHARED | LR. DEFAULTSIZE. Note that the system images must be 
loaded as shared. 


Return value: 


A .Image object that represents the image specified. If an error happened, the object may not be 
valid. Use the isNull() method to check if the image is valid. If there was an error, 
.SystemErrorCode may help to determine the error. 


Example: 


flags = .DlgUtil^or(.Image^toID(LR DEFAULTSIZE), .Image^toID(LR SHARED), - 
. Image~toID(LR_LOADMAP3DCOLORS) ) 


questionIcon = .Image~getImage(.Image~toID(IDI_QUESTION) , Е 
.Image^toID(IMAGE ICON), = 
.Size^new(0, 0), flags) 

if questionIcon"isNull then до 


say ?'Error getting the question icon. Error code:’ .SystemErrorCode 
end 


/* Note that you can always use the raw numeric value for the args. 
* This works just as well: 

*/ 

questionIcon = .Image^getImage(32514, 1, .Size^new(0, 0), 36928) 


ooRexx OODialog Reference Version 4.0.0 751 


Chapter 25. Resources 


if questionIcon"isNull then до 
say ’Error getting the question icon. Error code:’ .SystemErrorCode 


end 


25.1.4. fromFiles (Class method) 


»»--fromFiles(--files--4-------- D 5 oa шеше +--)---->< 
*-,-type-* +-,-size-+ +-,-flags-+ 


Gets an array of .Image objects, using an array of file names. This method is useful to load more than one 
image at a time, when all the images have the same specifications, type, size, and flags. 


Details 
Sets the .SystemErrorCode variable. 
Raises syntax errors when incorrect arguments are detected. 


Provides an interface to the Win32 API: LoadImage O. Use the MSDN library documentation to get 
more information on the arguments to this method. 


Arguments: 


files 


An array of file names to use to instantiate the .Image objects. The array can contain any 
number of file names, but it can not be sparse. That is, each index of the array must contain a 
file name. If an incorrect item is detected in the array, then a syntax error is raised and no 
images are returned. 

On the other hand, if there is an error with the Win32 API loading an image, then no syntax 
error is raised. The index in the array for that image is left empty. One way to check for this 
type of error is to compare the number of items in the returned array with the number of items 
in file name array. 


type 
Specifies the type of the image, bitmap, icon, or cursor. You can use .[Image-toID() to get the 


correct numeric value for one of the following symbols: 
IMAGE BITMAP IMAGE ICON 
IMAGE CURSOR 


The default is IMAGE BITMAP. 
size 
A .Size object that specifies the size of the image. The default is a size of 0x0. Under most 


circumstances this indicates that the actual size of the image should be used. However, the 
MSDN library documentation should be consulted for other meanings. 
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flags 


The load resource flags for the LoadImage() API. The flags are one or more of the following 
symbols. You can use .Image-toID() to get the correct numeric value for any of the following 


symbols. The or method of the .DIgUtil class can be used to combine more than one of the 
symbols if needed. 


LR_DEFAULTCOLOR LR_CREATEDIBSECTION 
LR_DEFAULTSIZE LR_LOADFROMFILE 

LR LOADMAP3DCOLORS LR LOADTRANSPARENT 
LR MONOCHROMEB LR SHARED 


ГК VGACOLOR 
The default is ГК LOADFROMFILE. 


Return value: 


The method returns an array of .Image objects, one object for each image that was loaded from a 
file successfully. 


Example: 


25.1.5. fromIDs (Class method) 


»»--fronIDs(--ids,--4-------- +--+-------- +--+--------- +--)----- >< 


+-,-type-+ +-,-size-+ +-,-flags-+ 


Uses an array of resource IDs to instantiate and return an array of .Image objects. This method loads Ше 
system image resources referenced by the resource IDs in the array. The images must all be the same 
type and size, and use the same load flags. 
Details 

Sets the .SystemErrorCode variable. 

Raises syntax errors when incorrect arguments are detected. 


Provides an interface to the Win32 API: LoadImage O. Use the MSDN library documentation to get 
more information on the arguments to this method. 


Arguments: 


ids 


An array of resource IDs to use to instantiate the .Image objects. The array can contain any 
number of IDs, but it can not be sparse. That is, each index of the array must contain a number. 


If an incorrect item is detected in the array, then a syntax error is raised and no images are 
returned. 
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On the other hand, if there is an error with the Win32 API loading an image, then no syntax 
error is raised. The index in the array for that image is left empty. One way to check for this 


type of error is to compare the number of items in the returned array with the number of items 
in ID array. 


type 


Specifies the type of the image: bitmap, icon, or cursor. You can use .Image~toID() to get the 


correct numeric value for one of the following symbols: 
IMAGE BITMAP IMAGE ICON 
IMAGE CURSOR 


The default is IMAGE, ICON 
size 


A .Size object that specifies the size of the image. The default is a size of 0x0. Under most 
circumstances this indicates that the actual size of the image should be used. However, the 
MSDN library documentation should be consulted for other meanings. 


flags 


The load resource flags for the LoadImage() API. The flags are one or more of the following 
symbols. You can use .Image-toID() to get the correct numeric value for any of the following 
symbols. The or method of the .DIgUtil class can be used to combine more than one of the 
symbols if needed. 


ГК DEFAULTCOLOR ГК CREATEDIBSECTION 
ГК DEFAULTSIZE LR LOADFROMFILE 

LR LOADMAP3DCOLORS LR LOADTRANSPARENT 
LR MONOCHROMEB LR SHARED 


ГК VGACOLOR 
The default is LR SHARED | LR. DEFAULTSIZE. 


Return value: 


The method returns an array of .Image objects, one object for each system image that was loaded 
successfully. 


Example: 


25.1.6. colorRef (Class Method) 


»»-.Image^colorRef(--4---4--4----- +--+----- +--)-------------- >< 

+-R-+ +-,-G-+ +-,-B-+ 
The Windows API uses a COLORREF to specify a RGB color. This is a 32-bit number with a 
hexidecimal format of: 0x00bbggrr. The colorRef() method provides a way to construct a COLORREF 
from the red, green, and blue values. Each color value (red, green, or blue) is a whole number in the 
range of 0 to 255 inclusive. 
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Windows also defines 2 special values for a COLORREF, CLR_NONE and CLR_DEFAULT. To get the 
numeric value for either of these values use CLR_NONE or CLR_DEFAULT for the R argument. E.g., 
ref = .Image^colorRef ("CLR NONE"). 


Arguments: 


All the arguments are optional, with 0 being the default for any omitted argument. 


R 
The red component of the RGB color, or one of the CLR. NONE / CLR, DEFAULT keywords. 
Case is not significant for either of the two keywords. 

G 
The green component of the RGB value. 

B 


The blue component of the RGB value. 


Return value: 


The return is a valid RGB color, specified as a COLORREF. Some method arguments related to 
images or colors require a COLORREF. 


Example: 
ref = .Image^colorRef (245, 89, 255) 
say ?А fancy purple:? ref ? (Ох? || ref^d2x^right(8, ?0?)?)? 
say 


::requires ’oodPlain.cls’ 
/* Output: 
A fancy purple: 16734709 (Ох0ОЕЕБФЕБ) 


*/ 


25.1.7. getRValue (Class Method) 
»»-.Image^getRValue(--colorRef--)-------------------------- >< 


Returns the red component of а RGB color. 


Arguments: 


The single argument is: 


colorRef 


A RGB color, a COLORREF. See the colorRef() method for a brief discussion of these terms. 
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Return value: 


The return is the red component of the specified RGB color. 


Example: 


progressBar = self~getProgressBar("IDC_PB_FILES") 
if progressBar <> .nil then do 
purple = .Image~colorRef (245, 89, 255) 


say ’Going to set the background color for the progress bar’ 
oldColor = progressBar^backgroundColor (purple) 


say ?014 background color was:? oldColor ’ (Ох? о19Со10г742х”)? 


say ?^ Red: ^" .Image~getRValue(oldColor) 
say ? Green:? .Image^getGValue(oldColor) 
say ? Blue: ? .IMage^getBValue(oldColor) 
say 

end 


/* Output might be: 


Going to set the background color for the progress bar 
01а background color was: 11460781 (OxAEEOAD) 


Red: 173 

Green: 224 

Blue: 174 
ж/ 


25.1.8. getGValue (Class Method) 
»»-.Image^getGValue(--colorRef--)-------------------------- >< 
Returns the green component of a RGB color. 


Arguments: 


The single argument is: 


colorRef 


A RGB color, a COLORREF. See the colorRef() method for a brief discussion of these terms. 


Return value: 


The return is the green component of the specified RGB color. 


Example: 


See the example for the getRValue() method. 
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25.1.9. getBValue (Class Method) 
»»-.Image^getBValue(--colorRef--)-------------------------- >< 


Returns the blue component of а RGB color. 


Arguments: 


The single argument is: 


colorRef 


A RGB color, a COLORREEF See Ше colorRef() method for a brief discussion of these terms. 


Return value: 


The return is the blue component of the specified RGB color. 


Example: 


See the example for the getRValue() method. 


25.1.10. handle 


>>--вапе-------------- шысы SS зы шнш шз << - - >< 
Returns the Windows system handle to the image this object represents. It is an error to invoke this 
method if the image is null, or after the image has been released. 


Currently, the handle is only useful for display. In the ooDialog framework, methods that use images for 
arguments, use the .Image object, not the image handle. Older methods that use a bitmap handle for a 
argument will not work with this handle. 


Arguments: 


The method does not have an argument. 


Return value: 


The return is the handle to the image. 


Example: 


hIcon - .Image^getImage(.Image^toID(IDI. QUESTION), .Image^toID(IMAGE ICON)) 
say ’hIcon: ^" hIcon 
say ? handle:’ hIcon" handle 


/* Output to the console might be (on a 64-bit Windows system) 
ЪТсоп: an Image 


handle: 0x000000000001002B 
*/ 
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25.1.11. release 


>2--гейваве------------------------------<- -<- >< 
Releases Ше image. This will free up operating system resources used for Ше image. See the introduction 
to the .Image class for some discussion on releasing an image. 


Once an image object has been released, it is an error to use the object. However, the isNull() and 
systemErrorCode() methods can always be used. The isNull() method will return .true after an image 
object has been released. Shared images should not be released, the operating system manages them. To 
prevent the programmer from accidentally releasing a shared image, the .Image object tracks which 
images are loaded as shared and does not release a shared image if the programmer requests it. 


Details 
Sets the .SystemErrorCode variable. 


Arguments: 


There are no arguments. 


Return value: 


The possible return values are: 


No error detected. 


non-Zero 


The operating system error code. 


Example: 


In this example, when the user presses the Test button, the current image for the static control is 
replaced by the system question mark image. The old image is no longer needed and it is released. 


::method onTest 


iconControl = self~getStaticControl (IDC_ICON_QUESTION) 
if iconControl <> .nil then do 
hQuestion = .Image~getImage(.Image~toID(IDI_QUESTION), .Image^toID(IMAGE ICON)) 
say "Question icon:’ hQuestion~handle 
if hQuestion"isNull then do 
say ’errror code: .SystemErrorCode 
end 
else do 
image = iconControl~setImage (hQuestion) 
say ’Swapped images:’ 
say ’ new icon:’ hQuestion^" handle 
say ’ old icon: image^handle 


-- The old image is no longer needed. 
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ret = image release 
say "Released old image return:’ ret ’.SystemErrorCode:’ .SystemErrorCode 
end 
end 


/* Output on the screen, on a 64-bit system, might be: 


Question icon: 0x000000000001002B 
Swapped images: 
new icon: 0x000000000001002B 
old icon: 0x0000000001120639 
Released old image return: О .SystemErrorCode: 0 


*/ 


25.1.12. isNull 


Peo TLS MLL SSS Sea a SS a SSR aa нетна >< 


The isNull() method tests if the image object is valid. The image will be null if an error occurred when it 
was loaded, or if the image has been released. 


Arguments: 


There are no arguments. 


Return value: 


The method returns .true if the image is not valid, is null, and .false if the image is not null. 


Example: 


In this example the programmer wanted to load the system question mark icon, but used the wrong 
image type. (He uses IMAGE BITMAP instead of IMAGE ICON.) The system will refuse to load 
the image. To test if the image was loaded okay, use the isNull() method. Note that the getImage() 
method set the .SystemErrorCode. As in all software, the error codes are not always that 
informative. 


hQuestion = .Image^getImage(.Image^toID(IDI QUESTION), .Image~toID(IMAGE_BITMAP) ) 
if hQuestion~isNull then do 


say ’System Errror code: .SystemErrorCode 
say ’ System message: ^" SysGetErrorText(.SystemErrorCode) 
end 


/* Output would be: 


System Errror code: 1814 
System message: The specified resource name cannot be found in the image file. 
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*/ 


25.1.13. systemErrorCode 


>>--вуввешЕггогбове-----------<-------------+-+------+----<-- << >< 


The systemErrorCode attribute of Ше image object will reflect any system error codes that are detected 
while working with an image object. This is the same error code as the .SystemErrorCode is set to. This 
can be useful if the programmer wants to check for an error code at some point when it is possible that 
.SystemErrorCode has been reset. (See the example below.) 


Like the isNull() method this method can be invoked even when the image is not valid. However, it 
should not be used to check if the image is valid because it is possible for the value to be 0 and the image 
to be null. 


Arguments: 


There are no arguments to this method 


Return value: 


The value is usually 0, but may be a system error code if one was detected. 


Example: 


In this example the system error code attribute for an image is checked at a point in the life-cycle of 
the application when checking the .SystemErrorCode would be meaningless: 


::method onYes 
expose hIcon 


-- Need to release the icon image, but it is not always valid. 
if \ hIcon"isNull then hIcon^release 
else do 

say ?The icon image is not valid.’ 


say ’ Error when it was loaded: hIcon^systemErrorCode 
say ? System message: › SysGetErrorText (hIcon^systemErrorCode) 
end 


return self^ok:super 
/* Output might be: 
The icon image is not valid. 
Error when it was loaded: 2 
System message: The system cannot find the file specified. 


*/ 


/* Note that the below was the error that caused the above. The file name 


ж is actually ’shaveIce.ico’ not shavedIce.ico. 
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if iconControl <> .nil then do 
hIcon = .Image^getImage("shavedIce.ico", .Image~toID(IMAGE_ICON) ) 


25.2. ImageList Class 


An image list is a object used to efficiently manage large sets of images. Either icons or bitmaps. In an 
image list, all images are the same size and are accessed by a zero-based index. The images are in screen 
device format. Optionally, each image in the list can have a matching monochrome bitmap that is used as 
a mask to draw the image transparently. 


The .ImageList object acts as an interface to the underlying operating system Image List, which 
Microsoft calls a control. Although Microsoft calls the Image List a control and documents it with the 
other dialog controls, it is not a control in the same sense as button, edit, or list-view controls. It is not a 
window, all dialog controls are windows. It does not send or recieve window messages. Use the MSDN 
library documentation to get more information on exactly how Image Lists work. 


When an image list is no longer needed, it can be released. This frees up the system resources used for 
the images and the image list. The programmer releases an image list by using the release() method. 
Once an image list is released it can no longer be used. It is an error to inovke any method on the 
released object, except for the isNull() method. The isNull() method can be invoked any time to test if an 
image list is valid or not. It should go without saying that a programmer should not release an image list 
that is in use. 


Future versions of the .ImageList are intended to provide a complete interface to the underlying Image 
List control. At this time not all functionality is implemented. 


Requires: 
The ImageList class requires the class definition file ooDialog.cls: 


::requires "ooDialog.cls" 


Methods: 


Instances of the ImageList class implement the methods listed in the following table: 


Table 25-3. Image Instance Methods 




















Method... ... description page 
create (Class method) id 

new (Class method) new 

add add 

addMasked addMasked 

addIcon addIcon 
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Method... ... description page 
addImages addImages 

getCount getCount 
getImageSize getImageSize 
duplicate duplicate 

remove remove 

removeAll removeAll 

release release 

handle handle 

isNull isNull 





25.2.1. new (Class method) 


Currently it is not intended for the ooDialog programmer to instantiate an image list object directly using 
the new method. This may change in the future and will be documented at that time, if the intention 
changes. .ImageList objects are instantiated using the create() method. 


25.2.2. create (Class method) 


»»--create(--4-------- +-+--------- +-+-------- +-+------- 4----------- >< 
+--size--+ +-,-flags-+ +-,count-+ +-,grow-+ 


Creates a new empty image list of the type specified. 


Details 
Raises syntax errors when incorrect arguments are detected. 


Provides an interface to the ImageList_Create() API. Use the MSDN library documentation to get 
more information on the arguments to this method. 


The ILC_MIRROR and ILC_PERITEMMIRROR flags require Common Control Library version 
6.0 or later. If necessary use the comCtl32Version() method to determine the current version of the 
library. 

Arguments: 


The arguments are: 
size 


A .Size object that specifies the size of a single image in the image list. All images in an image 
list. have the same size. 
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If this argument is omitted the system default size for an icon is used. This size can vary 
depending on which version of Windows is running and whether the user has selected to use 
large icons or not. A typical size is 32 x 32 (in pixels.) 


flags 


The flags that specify the type of image list to create. The flags are one or more of the 
following symbols, but can include only one ПС COLOR value. You can use .Image-toID() 
to get the correct numeric value for any of the following symbols. The or method of the 


.DIgUtil class can be used to combine the symbols. 
ILC MASK ILC COLOR24 

ILC COLOR ILC COLOR32 

ILC COLORDDB ILC PALETTE 

ILC COLOR4 ПС MIRROR 

ILC COLOR8 ILC PERITEMMIRROR 
ILC COLORI6 


Return value: 


A new, empty, image list is returned. 


Note: It is theoretical possible for this method to fail and the returned image list to be null. However, 


in practice, it is virtually impossible to cause a failure. Using a size of 0 x 0 seems about the 
only way. 


Example: 


-- We set the flags to create a 24 bit color, masked image list. 
flags = .DlgUtil^or(.Image^toID(ILC COLOR24), .Image^toID(ILC MASK)) 


-- Create an empty .ImageList object: 
imageList - .ImageList^create(.Size^new(61, 46), flags, 10, 10); 


25.2.3. add 


»»--add(--image-4--------- *--)----------------------------- >< 


+-,-mask--+ 


Adds a bitmap image or images to the image list. The number of images is inferred from the width of the 
added bitmap. Optionally adds the mask for the bitmap(s). If the image list does not use a mask, the 
mask argument is ignored, even if it is present. 


Internally the image list makes a copy of the bitmap. After the method returns, the original image can be 
released if it is not needed anymore. 
Details 


Raises syntax errors when incorrect arguments are detected or if the image list is null. 


Provides an interface to the ImageList_Add() API. The MSDN library documentation can provide 
more information on this method. 
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Arguments: 


The arguments are: 


image 
The .Image object that represents the image to add. This must be a bitmap image. The width of 
the image determines the number of images added. (Remember all images in a image list are 
the same size.) 


mask 


The mask(s) to use with the image(s). This must be a bitmap image. 


Return value: 


On success, the index of the first image added is returned, otherwise -1 is returned. 


Example: 


This example sets the image list for a list-view control. The images are loaded from psdemolv.bmp 
which is a bitmap 16 pixels high by 64 pixels wide, containing 4 individual images. Since the image 
list is created with a size of 16 x 16, when the add() method is used, the image list infers that the 
bitmap is 4 images. 


-- Set the images for the items in the list-view. 
image = .Image~getImage("bmp\psdemolv. bmp") 
imageList = .ImageList^create(.Size^new(16, 16), .Image^toID(ILC COLOR8), 4, 0) 
if Mimage^isNull, \imageList~isNull then do 
imageList~add (image) 
lc^setImageList(imagelist, .Image^toID(LVSIL SMALL)) 


-- The image list makes a copy of the bitmap, so we can release it now. 
image^release 
end 


25.2.4. addMasked 
»»--addMasked(--image-,-cRef--)---------------------------------- >< 


Adds a bitmap image, or images, to the image list. The COLOREF cRef is used to generate the mask. 


Internally the image list makes a copy of the bitmap. After the method returns, the original image can be 
released if it is not needed anymore. 


Details 
Raises syntax errors when incorrect arguments are detected or if the image list is null. 


Provides an interface to Ше ImageList__AddMasked() API. The MSDN library documentation can 
provide more information on this method. 
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Arguments: 


The arguments are: 


image 


The .Image object that represents the image to add. This must be a bitmap image. The width of 
the image determines the number of images added. (Remember all images in a image list are 
the same size.) 


cRef 


The color to use to generate the mask. In the added image, each pixel that matches this color is 
changed to black, and the corresponding bit in the mask is set to 1. 


Return value: 


On success, the index of the first added image is returned, otherwise -1 is returned. 


Example: 


This example comes from a dialog with a Tab control. An image list is used to set an icon for each 
tab. Each icon is a colored letter on a white background. Using a white color to generate the mask 
causes the image to be drawn tranparently. The colored letter itself shows, and the rest of the image 
lets the underlying color show through. 


-- Add all the tabs, including the index into the image list for an icon for 
-- each tab. 
tc^AddFullSeq("Red", 0, ,"Green", 1, , "Moss", 2, , "Blue", 3, = 


"Purple", 4, , "Cyan", 5, , "Gray", 6) 


-- Create a COLORREF (pure white) and load our bitmap. 
cRef = .Image~colorRef(255, 255, 255) 
image = .Image~getImage("bmp\psdemoTab. bmp") 


-- Create our image list, as a masked image list. 

imageList = .ImageList^create(.Size^new(16, 16), Е 
.DlgUtil^or(.Image^toID(ILC COLOR24), - 
.Image^toID(ILC MASK)), - 
10, 0) 


if Mimage^isNull, \imageList~isNull then до 
imageList^addMasked(image, cRef) 


tc~setImageList (imageList) 


image release 
end 
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25.2.5. addicon 


»»--addIcon(--image--)----------------------------------------- >< 
Adds an icon or cursor image to the image list. If the image list is masked, then both the image and mask 
bitmaps of the icon or cursor are copied. If it is not masked, then only the image bitmap is copied. 


Internally the image list makes a copy of the bitmap. After the method returns, the original image can be 
released if it is not needed anymore. 


Details 
Raises syntax errors when incorrect arguments are detected or if the image list is null. 
Provides an interface to the ImageList_AddIcon() API. The MSDN library documentation can 
provide more information on this method. 

Arguments: 


The only argument is: 


image 


The .Image object that represents the image to add. This must be an icon or cursor image. 


yyy, 


Return value: 


This method returns the index of the added icon or cursor on success, otherwise -1 is returned. 


Example: 


Here the system icon images are loaded and then displayed in a list-view. Each icon will show in the 
list-view with the text for the icon being its numeric resource ID. Since the system icons are shared, 
the icon images are not released after they are added to the image list. 


ids = .array^new() ids[ 1] = .Image~toID(IDI_APPLICATION) 


ids[ 2] = .Image^toID(IDI HAND) ids[ 3] = .Image^toID(IDI QUESTION) 
ids[ 4] = .Image^toID(IDI EXCLAMATION) ids[ 5] = .Image~toID(IDI_ASTERISK) 
ids[ 6] = „аре 100 (ПТ WINLOGO) 


flags = .DlgUtil~or(.Image~toID(ILC_COLOR8), .Image^toID(ILC. MASK)) 
imageList = .ImageList^create(.Size^new(32, 32), flags, 20, 10) 
do i = 1 to ids^items 
image = .Image^getImage(ids[i], .Image^toID(IMAGE ICON)) 
imagelist^addIcon(image) 


end 


list^setImageList(imageList, .Image~toID(LVSIL_NORMAL) ) 
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do і = 1 to ids”items 
list^add(ids[il, i - 1) 
end 


25.2.6. addimages 


»»--addImages(--images--*--------- *--)--------------------------- >< 


Adds a number of images to the image list. The images are supplied in a non-sparse array and must all be 
of the same type. 


The images are added to the image list in the same order as they exist in the array. If an error occurs in 
the middle of processing the images, the method returns at that point. This means that images prior to the 
error will exist in the image list, but no images in the array after the error will be placed in the image list. 
Which images were placed in the image list can be determined by the return value of this method. 


Details 


Raises syntax errors when incorrect arguments are detected or if the image list is null. 


Arguments: 


The arguments are: 


images 


An array of non-null .Image objects. The array must not be sparse, that is each index in the 

array must contain an .Image ojbect. The images can be bitmaps, icons, or cursors, but each 
image in the array must be the same type. (Remember that curors are icons, so that the array 
can contain a mixture of icons and cursors.) Bitmaps can not be mixed with icons or cursors. 


cRef 


A COLORREF that is used to generate the mask if the image list is a masked image list. See 
the addMasked() method for more details on this argument. This argument is ignored if the 
images are not bitmaps, or if the image list is not masked. 


Return value: 


This method returns the image list index of the last successfully added image, or -1 if no images 
were added. 


Example: 


This example creates an image list from a number icons and then displays them in a list-view 
control in a dialog. 


list = self^getListControl(IDC LV. IMAGES) 


ooRexx OODialog Reference Version 4.0.0 767 


Chapter 25. Resources 


filesi = .array~new() 
filesi[ 1] = "Bee.ico" 
filesi[ 2] = "Camera.ico" 
filesi[ 3] = "Сатега1.ісо" 


filesi[ 4] = "Default.ico" 
filesi[ 5] = "Disabled.ico" 
filesi[ 6] = "Hot.ico" 
filesi[ 7] = "Lamp.ico" 
filesi[ 8] = "Mountain.ico" 
files1[ 9] = "Normal.ico" 
filesi[10] = "Penquin.ico" 
Ғі1еѕ1[11] = "Picture.ico" 
filesi1[12] = "Pushed.ico" 
filesi[13] = "Question32.ico" 
files1[14] = "Search32.ico" 
filesi[15] = "Skull.ico" 
files1[16] = "Stolen.ico" 
files1[17] = "Window.ico" 


size = .Size~new(32, 32) 


images = .Image^fromFiles(filesi, .Image^toID(IMAGE ICON), size) 


if images^items <> filesi^items then do 
say ’Error loading images.’ 


say ? System error:’ .SystemErrorCode 
say ? Message: 
return 

end 


count = images" items 


› SysGetErrorText(.SystemErrorCode) 


flags = .DlgUtil^or(.Image^toID(ILC COLOR24), .Image^toID(ILC  MASK)) 


imageList - .ImageList^create(size, flags, 20, 10); 


lastAdded = imageList^addImages (images) 
if lastAdded <> (count - 1) then do 
-- Not all images were added. 
-- in the list-view what was added. 
end 


We just ignore this and display 


-- Set the image list for the list-view's normal icons. 
list^setImageList(imagelist, .Image^toID(LVSIL NORMAL)) 


-- Add an item to the list-view for each image. The 


-- text for each item will be the icon file name and 


-- the icon will be the image we loaded. 
do 1 = 0 to lastAdded 

list^add(filesi[i * 1], i) 
end 
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25.2.7. getCount 


22== pet Coun tas 9S ss SSS SSS SS SSSR SSS SSeS SS SSS ee ees >< 


Determines the number of images in the image list. 


Details 
Raises a syntax error if the image list is null. 
Provides an interface to Ше ImageList_ImageCount () API. The MSDN library documentation can 
provide more information on this method. 

Arguments: 


There are no arguments. 


Return value: 


Returns the number of images currently in the image list. 


Example: 


::method displayImageListCount private 
use strict arg imageList 
say ’Image list:’ imageList^ handle ’has’ imagelist^getCount "images." 


/ж 


Possible output оп a Windows 64-bit system: 


Image list: 0х00000000000Ер420 has 17 images. 
*/ 


25.2.8. getlmageSize 
>2--пе шареб12е------------------------------------ >< 


Determines Ше size of Ше images in Ше image list. АП images in any single image list have Ше same 
size. 


Details 
Raises a syntax error if the image list is null. 
Provides an interface to Ше ImageList_IconSize() АРІ. The MSDN library documentation can 
provide more information on this method. 

Arguments: 


There are no arguments. 


Return value: 


The size of the images in the image list is returned in a .Size object. 


ooRexx OODialog Reference Version 4.0.0 769 


Chapter 25. Resources 


Example: 


::method displayImageListSize private 
use strict arg imageList 


в = imageList~getImageSize 


S^height "pixels high’ 


= 
Il 


S^width "pixels wide’ 
say ’Image list:’ imageList^ handle ’contains images’ h "by? w 


/ж 


Possible output on a Windows 64-bit system: 


Image list: Ox00000000000DCB20 contains images 32 pixels high by 32 pixels wide 
*/ 


25.2.9. duplicate 


22--düupiiCabtà---—---------——---—----e SSS SRS SS SSS a eiie >< 


Creates a duplicate image list. All information in the original image list is copied to the new image list. 
(Overlay images are not copied, but ooDialog does not have support for image list overlay images at this 
time.) The two image lists are independent. Adding, or removing, images from one image list has no 
effect on the other. 


Details 
Raises a syntax error if the image list is null. 
Provides an interface to the ImageList_Duplcate() API. The MSDN library documentation can 
provide more information on this method. 

Arguments: 


There are no arguments. 


Return value: 


The return is a copy of the image list. 


Example: 


This fictious example is from a point-of-sale application for a restaurant. The customer is presented 
with a list-view of menu items, each list-view item has a colorful icon depicting the selection. The 
customers place their orders through the application and wait-people then bring them their meal 
when it is ready. The dinner menu has all the items that the lunch menu does, plus some more. The 
customer can choose whether to order from the lunch menu or the dinner menu, so the lunch menu 
image list has to remain unchanged. 


::imethod getDinnerImageList private 
use strict arg lunchImageList 


dinnerList = lunchImageList~ duplicate 
fileArray = self^getDinnerlmageFiles 


770 ooRexx OODialog Reference Version 4.0.0 


Chapter 25. Resources 


dinnerList^addImages(fileArray) 


return dinnerList 


25.2.10. remove 


»»--remove(--index--)----------------------------------------- >< 


Removes the image at index from the image list. When the image is removed, all the indexes in the list 
are adjusted. Le., if the image at index 2 is removed, the image at index 3 becomes index 2, the image at 
index 4 becomes index 3, etc.. 


Details 
Raises syntax errors when incorrect arguments are detected or if the image list is null. 
Provides an interface to Ше ImageList Remove() АРІ. The MSDN library documentation can 
provide more information on this method. 

Arguments: 


The single argument is: 


index 


The index of the image to remove. 


Return value: 


This method returns true on success, otherwise false. 


Example: 


This example comes from the fictious point-of-sale application for a restaurant. Sometimes the chef 
runs out of a menu item and the item is then removed from the list-view so that the customers can 
no longer order it. (Rigorous error checking is not done because the application was written by one 
of the waiters.) 


::method removeFromMenu private 
use strict arg index 


menu = self~getListControl (IDC_LV_MENU) 


bigIcons = menu~getImageList (. Image~toID(LVSIL_NORMAL) ) 
bigIcons~remove (index) 


smallIcons = menu~getImageList (.Image~toID(LVSIL_SMALL) ) 
smallIcons~remove (index) 


stateIcons = menu^getImageList(.Image^toID(LVSIL STATE)) 
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stateIcons~ remove (index) 
пепо” delete (index) 


return 0 


25.2.11. removeAll 


>2--гещоуей | 1----тея----нненян-яясанян SSS a SRS SS SSS SS SSSR SSS emer >< 


Removes all images from the image list. 


Details 
Raises a syntax error if the image list is null. 
Provides an interface to Ше ImageList_RemoveAl1() API. The MSDN library documentation can 
provide more information on this method. 

Arguments: 


There are no arguments to this method. 


Return value: 


The method returns true on success, false otherwise. 


Example: 


This example is a continuation of the fictious restaurant point-of-sale application. The waiter that 
wrote the application did not like to work past the normal closing time. The application has a 
feature that removes all the menu items as it gets near closing time to prevent customers from 
ordering something they do not have time to finish eating. (However, the waiter noticed that he often 
got huge tips from customers that had drinks after their meal.) 


::method stopOrders private 
menu = self~getListControl (IDC_LV_MENU) 


bigIcons = menu~getImageList (. Image~toID(LVSIL_NORMAL) ) 
bigIcons~ removeAll 


smallIcons = menu^getImageList(.Image^toID(LVSIL SMALL)) 
smallIcons~ removeAll 


stateIcons = menu^getImageList(.Image^toID(LVSIL STATE)) 
stateIcons” removeAll 


menu^deleteAll 
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self^addAfterDinnerDrinks (menu) 


return 0 


25.2.12. release 


22-3P6lease--c----2------— 0e v еы er e cr e ee а >< 


Releases the image list allowing the operating system to reclaim the resources used by the image list. 
Once the image list has been released, it can no longer be used. 


Arguments: 


There are no arguments to this method. 


Return value: 


This method always returns 0. 


Example: 


This example comes from a program that runs continuously. During the life-cycle of the application 
it displays and then closes a dialog that creates some image lists. The image lists are always 
different depending on the state of things. Each time the dialog closes, it releases the image lists it 
created to free up the operating system resources. 


::method ok 
self~cleanUp 
return се| Е ок: super 


: :шетпод cancel 
self~cleanUp 
return self~cancel:super 


::method cleanUp private 
expose coolTempImages warningImages buidingStatusImages 


if coolTempImages \== .nil then coolTempImages^release 


if warningImages \== .nil then warningImages^release 
if buildingStatusImages \== .nil then buildStatusImages^release 
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25.2.13. handle 


>? = hand les == ssa See RRS шз шышы шы SSS е ы Sear SSeS >< 
Returns the Windows system handle to the image list this object represents. It is an error to invoke this 
method if the image list is null, or after the image has been released. 


At this time, the handle is only useful for display. In the ooDialog framework, methods that use image 
lists for arguments, use the .ImageList object, not the image list handle. 


Arguments: 


There is no argument to this method. 


Return value: 


The return is the image list handle. 


Example: 


::method displayImageList private 
use strict arg imageList 
say ’Currently using this image list: imageList^ handle 


/ж 


Possible output оп a Windows 64-bit system: 


Currently using this image list: 0х000000000000СВ20 
*/ 


25.2.14. isNull 
>2-- ви aa зыш сонны ышы нетна >< 


Used to check if an image list is valid. This method can be invoked on any image list, even after it has 
been released. An image list will always be null after it has been released. It is conceivable that, if an 
error occurs during an image list creation, the returned image list might be null. However, this is 
extemely unlikely. Therefor, for all practical purposes, an image list will only be null after it has been 
released. 


Arguments: 


There are no arguments to this method. 


Return value: 


This method returns true if the image list is null, otherwise false. 


Example: 


This example comes from some test code. 


-- See if we can create an image list with no size. 
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imageList = .ImageList^create(.Size^new(0, 0), .Image~toID(ILC_COLOR24), 20, 10) 
if imageList~isNull then do 

say Сап not create a 0 x 0 image list." 

return .false 
end 


return .true 


/* 
Output will be: 


Can not create a 0 x O image list. 


*/ 


25.3. Resourcelmage Class 


Resource Images represent modules that contain resources. These modules are binary executable files, 
which on Windows are for all practical purposes .exe and .dll files. Before an application can use a 
resource in a module, the resource must be loaded from the module into memory. Once in memory, the 
application needs a handle to the specific resource in order to work with it. 


The ResourceImage class contains methods and function to assist in the loading of resources into 
memory and obtaining handles to the desired resources. ooDialog has always had, limited, access to 
resources in modules through the ResDialog class. The ResourceImage class expands that access, both 
improving it and making the access avaiable in any ooDialog program, with or without ResDialog 
objects. The class supports the loading of, and obtaining handles to, resources from any binary 
executable file. 


The class provides the release() method to free up system resources if a module containing the resources 
is no longer needed. The general remarks concerning freeing the .Image class are applicable here. The 
release() method will ignore requests to release the module when it is known absoulutely that the module 
should not be released, such as in the case the module is the oodialog.d11. In other cases only the 
programmer can know if the module should or shouldn't be released. In those cases, the ResourceImage 
class will do as requested. As with the images that Ше .Image class represents, the system resources used 
by the module the ResourceImage class represents will be automatically cleaned up when the interpreter 
process ends. The comments about why would a programmer want to release resources in the .Image 
class remarks are equally apropos here. 


Note: The Resourcelmage class is new in ooDialog as of ooRexx version 4.0.0. Its first 
implementation supports image resources and provides the basic framework upon which to expand 
in the future. 
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Requires: 
The ResourceImage class requires the class definition file ooDialog.cls: 


::requires "ooDialog.cls" 


Methods: 


Instances of the ResourceImage class implement the methods listed in the following table: 


Table 25-4. Name Instance Methods 



































Method... ... description 
new (Class method) new 

getImage getImage 
getImages getImages 

handle handle 

isNull isNull 

release release 
systemErrorCode systemErrorCode 





25.3.1. new (Class method) 


»»--new(--fileName--4-------- *--)-------------------------- >< 
+-,-dlg--+ 


Instantiates a new resource image that represents the module specified by fileName. 


Details 
Sets the .SystemErrorCode variable. 


Raises syntax errors when incorrect arguments are detected. 


Arguments: 


The arguments are: 


fileName 


Specifies the file name of the module containing resources that the ooDialog program wants to 
access. If the module is in the path, (or the current directory,) the file name alone is sufficent. 
The operating system will search the path for the file as it normally does when a program is 
executed. If the module is not in the path then a full, or relative, file name is required. 


dig 


The second optional dig argument is a dialog object in the current program. It specifies that the 
module containing the resources that the ooDialog program wants to acess is one of the 


776 ooRexx OODialog Reference Version 4.0.0 


Chapter 25. Resources 


modules already avalable to the program. That is, either the oodialog.d11 module, or the 
module used for a ResDialog. 


To specify the oodialog.d11 module, the file name must be oodialog.dll and the dialog object 
can be any instantiated dialog in the current program. 


To specify the module used with a ResDialog, the dialog object must be the instantiated 
ResDialog dialog object. 


Return value: 


Returns a new ResourcelImage object. This object may be null if an error occurred. Use the isNull() 
method to check for this. Both the .SystemErrorCode or the systemErrorCode() method should 
contain an error code if the object is null. 


Example: 


This example instantiates a resource image using the oodialog.dll module and uses it to load the 
generally available icon resources from that module. The icons are then displayed in a list-view 
control. 


::method initDialog 
expose list 


list = self^getListControl(IDC LV IMAGES) 


ids = .array^new() 

ids[1] = self^constDir[IDI. DLG OODIALOG] 
ids[2] = self^constDir[IDI DLG APPICON] 

ids[3] = self~constDir [IDI_DLG_APPICON2] 
ids[4] = self~constDir [IDI_DLG_OOREXX] 


11 
12 


SM_CXICON 
SM_CYICON 


size = .Size^new(.DlgUtil^getSystemMetrics(SM, CXICON), .DlgUtil~getSystemMetrics (SM_CYICON) ) 


oodModule = .Resourcelmage^new("oodialog.dll", self) 
icons = oodModule^getlImages(ids, .Image^toID(IMAGE ICON), size) 


flags = .DlgUtil^or(.Image^toID(ILC, COLOR24), .Image~toID(ILC_MASK) ) 
imageList = .ImageList^create(size, flags, 4, 0) 
imageList~ addImages (icons) 


list~setImageList(imageList, .Image^toID(LVSIL NORMAL)) 


names - .array^new() 
names[1] = "IDI_DLG_OODIALOG" 


names[2] = "IDI_DLG_APPICON" 
names[3] = "IDI_DLG_APPICON2" 
names[4] = "IDI_DLG_OOREXX" 


do і = 1 to ids^items 
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list^add(names[i] ’(’ids[i]’)’, i - 1) 
end 


25.3.2. getlmage 


»»--getImage(--id--4-------- +--+-------- +--+--------- +--)----- >< 
+-,-type-+ +-,-size-+ +-,-flags-+ 


Loads the specified image resource in the module and returns a new .Image object. 


Note: LoadImage() is the underlying Windows API used here. This method is very similar to the 
дейтаде() method of the .Image class. The documentation for that method may provide additional 
insight. 


Details 
Raises a syntax error if the resource image is null. 
Sets the .SystemErrorCode variable. 
Raises syntax errors when incorrect arguments are detected. 
Provides an interface to the Win32 API: LoadImage O. Use the MSDN library documentation to get 
more information on the arguments to this method. 
Arguments: 


The arguments are: 


id 
The resource id of the image in the module. 
Note: At this time symbolic IDs are not supported for this argument. That restriction may be 
lifted in a furture version of ooDialog. 
type 


Specifies the type of the image: bitmap, icon, or cursor. You can use .[mage-toID() to get the 


correct numeric value for one of the following symbols: 
IMAGE BITMAP IMAGE ICON 
IMAGE CURSOR 


The default is IMAGE BITMAP 
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A .Size object that specifies the size of the image. The default is a size of 0x0. Under most 
circumstances this indicates that the actual size of the image should be used. However, the 
MSDN library documentation for LoadImage() should be consulted for other meanings. 


flags 


The load resource flags for the LoadImage() API. The flags are one or more of the following 
symbols. You can use .Image-toID() to get the correct numeric value for any of the following 


symbols. The or method of the .DIgUtil class can be used to combine more than one of the 
symbols if needed. 


LR DEFAULTCOLOR ТК CREATEDIBSECTION 
ГК DEFAULTSIZE LR LOADFROMFILE 

LR LOADMAP3DCOLORS LR LOADTRANSPARENT 
LR MONOCHROMEB LR SHARED 


ГК VGACOLOR 
The default is LR. SHARED. 


Return value: 


This method returns an .Image object that represents the specified image resource in the module. 
The image may be null if an error occurred, for instance if no image resource was found. 


Example: 
This example uses a ResDialog with a static control that displays a bitmap image. The image for the 


static control is obtained from the resource-only DLL used by the ResDialog. 


::class SimpleDialog subclass ResDialog inherit AdvancedControls MessageExtensions 


::method initDialog 


resources - .ResourceImage^new("simpleImage.dll", self) 


image = resources^getlImage(self^constDir[ID ВМР. IMAGE1]) 


picture = self^getStaticControl(IDC. BMP PICTURE) 
oldImage = picture^setlImage(image) 


25.3.3. getlmages 


>>--get Images (--ids ,--+-------- +--+-------- +--+--------- +--)----- >< 


*t-,-type-* +-,-size-+ +-,-flags-+ 


Loads а number of image resources from Ше module. An array of resource IDs is used to specify which 
image resources. All the image resources must have the same characteristics. That is they must all be the 
same type and use the same flags. If the type is bitmap, and the flags include LR_DEFAULTSIZE, and 


the size is Ох 0, then the size of the image will be the actual resource size. Otherwise, all the images also 
need to be the same size. 
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Note: LoadImage() is the underlying Windows API used here. This method is very similar to the 
fromIDs() method of the .Image class. The documentation for that method can provide additional 
information. 


Details 
Raises a syntax error if the resource image is null. 
Sets the .SystemErrorCode variable. 
Raises syntax errors when incorrect arguments are detected. 


Provides an interface to the Win32 API: LoadImage(). You can use the MSDN library 
documentation to get more information on the interaction between the flags, size, and type 
arguments. 


Arguments: 


The arguments are: 


ids 
An array of the resource IDs of the image resources in the module. The array can contain any 
number of IDs, but it can not be sparse. That is, each index of the array must contain a number. 


If an incorrect item is detected in the array, then a syntax error is raised and no images are 
returned. 


If there is an error with an individual image resource, then the index in the array for that image 
is left empty. One way to check for this type of error is to compare the number of items in the 
returned array with the number of items in ID array. 


type 
Specifies the type of the image: bitmap, icon, or cursor. You can use .Image-toID() to get the 


correct numeric value for one of the following symbols: 
IMAGE BITMAP IMAGE ICON 
IMAGE CURSOR 


The default is IMAGE BITMAP. 


size 
A .Size object that specifies the size of the image. The default is a size of 0x0. Under most 


circumstances this indicates that the actual size of the image should be used. However, the 
MSDN library documentation should be consulted for other meanings. 


flags 


The load resource flags for the LoadImage() API. The flags are one or more of the following 
symbols. You can use .Image-toID() to get the correct numeric value for any of the following 
symbols. The or method of the .DIgUtil class can be used to combine more than one of the 


symbols if needed. 
ГК DEFAULTCOLOR ГК CREATEDIBSECTION 
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LR_DEFAULTSIZE LR_LOADFROMFILE 
LR LOADMAP3DCOLORS LR LOADTRANSPARENT 
LR MONOCHROMEB LR SHARED 


ГК VGACOLOR 
The default is LR. SHARED. 


Return value: 


The return will be an array of .Image objects, one for each resource ID specified in the ids array, if 
there is no error. If there is an error loading the image of any specified ID, the corresponding index 
in the returned array will be empty. 


If there is an error, both the .SystemErrorCode and the systemErrorCode attribute of this resource 
image will be set (to the same code.) It is conceivable that an error could occur where the system 
does not set an error code, but unlikely. 


Example: 


The following is a complete working dialog. Four bitmap images are used. Each time the user clicks 
the next button, the next image is displayed. 


An array is constructed containing the resource IDs of the 4 images. A new resource image object is 
instantiated from the images.d11 module. The getImages() method is then used to get an array of 4 
.Image objects, using the array of resource IDs. 


/* Simple Dialog to display some images */ 
dlg = .SimpleDialog^new( , ’simpleImage.h’) 
if dlg^initCode = 0 then до 
dlg^createCenter(200, 247, "Simple Image Viewer", "", , "MS Shell Dlg 2", 8) 
dlg^Execute("SHOWTOP", 14) 
end 


dlg^Deinstall 


return 0 
-- End of entry point. 


::requires "oodWin32.cls" 

::class SimpleDialog subclass UserDialog inherit AdvancedControls MessageExtensions 

::method defineDialog 
self^addStatic(IDC BMP PICTURE, 10, 10, 20, 17, "BITMAP REALSIZEIMAGE") 
self^addStatic(IDC ST DESCRIPTION, 14, 190, 176, 20, "TEXT LEFT", "Description") 
self^addButton(IDC PB. NEXT, 10, 223, 50, 14, "Next", onNext) 


self^addButton(IDOK, 140, 223, 50, 14, "Ok", ok, "DEFAULT") 


::method initDialog 
expose picture images description descriptions nextImage 


ids = .array^new 
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ids[ 1] = self~constDir [ID_BMP_IMAGE1] 
ids[ 2] = self~constDir [ID_BMP_IMAGE2] 
ids[ 3] = self~constDir[ID_BMP_IMAGE3] 
ids[ 4] = self~constDir [ID_BMP_IMAGE4] 


descriptions = .array^new 

descriptions[1] = "Conrad, King of the Hill" 
descriptions[2] = "Berk, Squint Eye" 
descriptions[3] = "Cienna, Deer in the Headlights" 
descriptions[4] = "Vail, The Flower Child" 


picture = self~getStaticControl(IDC_BMP_PICTURE) 
description = self^getStaticControl(IDC ST. DESCRIPTION) 
self^connectButton(IDC PB. NEXT, onNext) 


nextImage = 1 
module = „Вевошгсешаре пен("1шарез.911") 
images = module~getImages (ids) 


self^onNext 


::method onNext 
expose picture description images descriptions nextImage 


if nextImage > images^items then nextImage = 1 
picture^setImage (images [nextImage] ) 


description~setText (descriptions [nextImage] ) 
nextImage += 1 


25.3.4. release 


cs N= | > a a шшш шулы ы шнен >< 


Releases the resource module so that the operating system can reclaim the system resources. After the 
resource image has been released it can no longer be used. The programmer should not release the 
resource image while resources loaded from the module are still in use. 


If the resource image represents the oodialog.d11 module, or the module used for a ResDialog, then the 
resource image should never be released. The release() method will ignore release requests in those 
sitautions. 


Details 
Raises a syntax error if the resource image is null. 


Sets the .SystemErrorCode variable. 
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This method return the system error code, which will be zero if there is no error, and non-zero if 


there is an error. The .SystemErrorCode is also set to this value. 


Example: 


In this example, the images for an image list are loaded from a resource module. The resource 
module is no longer needed after the image list is created. Since an image list makes a copy of the 
images added to it, once the image list has all the images added to it, the resource image can be 


released. 


::method getImages private 
use strict arg resourceIDs, size, ilFlags 


imageList = .ImageList^create(size, ilFlags, 20, 10); 
module = .Resourcelmage^new("zooImages.dll") 
images = module^getImages(resourceIDs) 
imageList~ addImages (images) 
do i = 1 to images~items 
images [i]~release 
end 


module^release 


return imageList 


25.3.5. handle 


22--handle---------5-------——- coco ш SS зыш ызыны шы зы ны ыны шышы Ыза >< 


Returns the Windows system handle for the resource module. It is an error to invoke this method if the 


resource image is null, or after the resource image has been released. 


At this time, the handle is only useful for display. 


Arguments: 


There are no arguments. 


Return value: 


The return is the handle for the module the resource image represents. 
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Example: 


This example ... 


::method showHandles 


oodMod = .ResourceImage^new("oodialog.dll", self) 
resMod = .Resourcelmage^new("simpleImage.dll", self) 


say ?The oodialog.dll module handle is: ?^ oodMod^ handle 
say ’The resource module for this ResDialog is:’ гезМод” handle 


/* The output, for a ResDialog, might be: 


The oodialog.dll module handle is: 0x009E0000 
The resource module for this ResDialog is: OxOOAF0000 
*/ 


25.3.6. isNull 
22--y8Nullc--—-——-AULUE ы-ы ышк ee Ата >< 


Determines if the resource image is valid. isNu11() will always return .true after the resource image has 
been released. It will also return .true if there was an error instantiating a new resource image object. 


Arguments: 


There are no arguments. 


Return value: 


Returns .true if the object is null, otherwise .false. 


Example: 


It is a good idea to check that a new resource image object is valid before using it. 


::imethod initDialog 


resourceModule = .ResourceImage~new("simpleImage.dll", self) 
if \ resourceModule^isNull the do 

image = resources^getlImage(self^constDir[ID. BMP IMAGE1]) 
else do 

-- Some error handling here. 
end 
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25.3.7. systemErrorCode 


22--8ystemErrorCode------——--—----e eee SRS SS Sa Se SRS SSS SSS eas >< 


When a method for a resource image is invoked that sets the .SystemErrorCode, Ше systemErrorCode 
attribute of the resource image object is also set. This can be useful if the programmer wants to check for 
an error code at some point when it is possible that .SystemErrorCode has been reset. 


This method can always be invoked, even if the resource image is null. It is very similar to the 
systemErrorCode() method of the .Image class and the documentation for that method is generally 
applicable here. 


Arguments: 


This method does not take any arguments. 


Return value: 


The return is a system error code, which will usually be 0, no error. 


Example: 


This example uses the systemErrorCode attribute to get more information on a possbile error, rather 
than the .SystemErrorCode. 


::method initDialog 


mod = .Resourcelmage^new("simpleImage.dll", self) 

if mod^isNull the до 
self^writeToLog("Error with resource module simpleImage.dll") 
self^writeToLog(" RC: " mod^systemErrorCode) 
self^writeToLog(" msg:" SysGetErrorText (mod^systemErrorCode) 
return 

end 


image = resources^getlImage(self^constDir[ID BMP. IMAGE1]) 
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Any reference to a non-open source product, program, or service is not intended to state or imply that 
only non-open source product, program, or service may be used. Any functionally equivalent product, 
program, or service that does not infringe any Rexx Language Association (RexxLA) intellectual 
property right may be used instead. However, it is the user’s responsibility to evaluate and verify the 
operation of any non-open source product, program, or service. 


Any performance data contained herein was determined in a controlled environment. Therefore, the 
results obtained in other operating environments may vary significantly. Some measurements may have 
been made on development-level systems and there is no guarantee that these measurements will be the 
same on generally available systems. Furthermore, some measurement may have been estimated through 
extrapolation. Actual results may vary. Users of this document should verify the applicable data for their 
specific environment. 


Information concerning non-open source products was obtained from the suppliers of those products, 
their published announcements or other publicly available sources. RexxLA has not tested those products 
and cannot confirm the accuracy of performance, compatibility or any other claims related to 
non-RexxLA packages. Questions on the capabilities of non-RexxLA packages should be addressed to 
the suppliers of those products. 


All statements regarding RexxLA’s future direction or intent are subject to change or withdrawal without 
notice, and represent goals and objectives only. 


This information contains examples of data and reports used in daily business operations. To illustrate 
them as completely as possible, the examples include the names of individuals, companies, brands, and 
products. All of these names are fictitious and any similarity to the names and addresses used by an 
actual business enterprise is entirely coincidental. 


A.1. Trademarks 


Open Object Rexx™ and ooRexx™ are trademarks of the Rexx Language Association. 


The following terms are trademarks of the IBM Corporation in the United States, other countries, or both: 


1-2-3 

AIX 

IBM 
Lotus 
OS/2 
8/390 
VisualAge 


AMD is a trademark of Advance Micro Devices, Inc. 


Intel, Intel Inside (logos), MMX and Pentium are trademarks of Intel Corporation in the United States, 
other countries, or both. 


Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the Unites States, other 
countries, or both. 


Linux is a trademark of Linus Torvalds in the United States, other countries, or both. 


Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in 
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the United States, other countries, or both. 
UNIX is a registered trademark of The Open Group in the United States and other countries. 


Other company, product, or service names may be trademarks or service marks of others. 


A.2. Source Code For This Document 


The source code for this document is available under the terms of the Common Public License v1.0 
which accompanies this distribution and is available in the appendix Common Public License Version 
1.0. The source code itself is available at 

http://sourceforge.net/project/showfiles.php?group id-119701. 


The source code for this document is maintained in DocBook SGML/XML format. 


і Уч crated DocBook 


with Tid А 
is The Souree for 


Documentation 
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THE ACCOMPANYING PROGRAM IS PROVIDED UNDER THE TERMS OF THIS COMMON 
PUBLIC LICENSE ("AGREEMENT"). ANY USE, REPRODUCTION OR DISTRIBUTION OF THE 
PROGRAM CONSTITUTES RECIPIENT’S ACCEPTANCE OF THIS AGREEMENT. 


B.1. Definitions 


"Contribution" means: 


1. in the case of the initial Contributor, the initial code and documentation distributed under this 
Agreement, and 


2. in the case of each subsequent Contributor: 
a. changes to the Program, and 
b. additions to the Program; 
where such changes and/or additions to the Program originate from and are distributed by that particular 
Contributor. A Contribution ’originates’ from a Contributor if it was added to the Program by such 
Contributor itself or anyone acting on such Contributor’s behalf. Contributions do not include additions 


to the Program which: (i) are separate modules of software distributed in conjunction with the Program 
under their own license agreement, and (ii) are not derivative works of the Program. 


"Contributor" means any person or entity that distributes the Program. 


"Licensed Patents " mean patent claims licensable by a Contributor which are necessarily infringed by 
the use or sale of its Contribution alone or when combined with the Program. 


"Program" means the Contributions distributed in accordance with this Agreement. 


"Recipient" means anyone who receives the Program under this Agreement, including all Contributors. 


B.2. Grant of Rights 


1. Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, 
worldwide, royalty-free copyright license to reproduce, prepare derivative works of, publicly 
display, publicly perform, distribute and sublicense the Contribution of such Contributor, if any, and 
such derivative works, in source code and object code form. 


N 


. Subject to the terms of this Agreement, each Contributor hereby grants Recipient a non-exclusive, 
worldwide, royalty-free patent license under Licensed Patents to make, use, sell, offer to sell, import 
and otherwise transfer the Contribution of such Contributor, if any, in source code and object code 
form. This patent license shall apply to the combination of the Contribution and the Program if, at 
the time the Contribution is added by the Contributor, such addition of the Contribution causes such 
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combination to be covered by the Licensed Patents. The patent license shall not apply to any other 
combinations which include the Contribution. No hardware per se is licensed hereunder. 


3. Recipient understands that although each Contributor grants the licenses to its Contributions set 
forth herein, no assurances are provided by any Contributor that the Program does not infringe the 
patent or other intellectual property rights of any other entity. Each Contributor disclaims any 
liability to Recipient for claims brought by any other entity based on infringement of intellectual 
property rights or otherwise. As a condition to exercising the rights and licenses granted hereunder, 
each Recipient hereby assumes sole responsibility to secure any other intellectual property rights 
needed, if any. For example, if a third party patent license is required to allow Recipient to distribute 
the Program, it is Recipient’s responsibility to acquire that license before distributing the Program. 


4. Each Contributor represents that to its knowledge it has sufficient copyright rights in its 
Contribution, if any, to grant the copyright license set forth in this Agreement. 


B.3. Requirements 


A Contributor may choose to distribute the Program in object code form under its own license 
agreement, provided that: 


1. it complies with the terms and conditions of this Agreement; and 
2. its license agreement: 


a. effectively disclaims on behalf of all Contributors all warranties and conditions, express and 
implied, including warranties or conditions of title and non-infringement, and implied 
warranties or conditions of merchantability and fitness for a particular purpose; 


b. effectively excludes on behalf of all Contributors all liability for damages, including direct, 
indirect, special, incidental and consequential damages, such as lost profits; 


c. states that any provisions which differ from this Agreement are offered by that Contributor 
alone and not by any other party; and 


d. states that source code for the Program is available from such Contributor, and informs 
licensees how to obtain it in a reasonable manner on or through a medium customarily used for 
software exchange. 


When the Program is made available in source code form: 


1. it must be made available under this Agreement; and 
2. a copy of this Agreement must be included with each copy of the Program. 
Contributors may not remove or alter any copyright notices contained within the Program. 


Each Contributor must identify itself as the originator of its Contribution, if any, in a manner that 
reasonably allows subsequent Recipients to identify the originator of the Contribution. 
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B.4. Commercial Distribution 


Commercial distributors of software may accept certain responsibilities with respect to end users, 
business partners and the like. While this license is intended to facilitate the commercial use of the 
Program, the Contributor who includes the Program in a commercial product offering should do so in a 
manner which does not create potential liability for other Contributors. Therefore, if a Contributor 
includes the Program in a commercial product offering, such Contributor ("Commercial Contributor") 
hereby agrees to defend and indemnify every other Contributor ("Indemnified Contributor") against any 
losses, damages and costs (collectively "Losses") arising from claims, lawsuits and other legal actions 
brought by a third party against the Indemnified Contributor to the extent caused by the acts or omissions 
of such Commercial Contributor in connection with its distribution of the Program in a commercial 
product offering. The obligations in this section do not apply to any claims or Losses relating to any 
actual or alleged intellectual property infringement. In order to qualify, an Indemnified Contributor must: 
a) promptly notify the Commercial Contributor in writing of such claim, and b) allow the Commercial 
Contributor to control, and cooperate with the Commercial Contributor in, the defense and any related 
settlement negotiations. The Indemnified Contributor may participate in any such claim at its own 
expense. 


For example, a Contributor might include the Program in a commercial product offering, Product X. That 
Contributor is then a Commercial Contributor. If that Commercial Contributor then makes performance 
claims, or offers warranties related to Product X, those performance claims and warranties are such 
Commercial Contributor's responsibility alone. Under this section, the Commercial Contributor would 
have to defend claims against the other Contributors related to those performance claims and warranties, 
and if a court requires any other Contributor to pay any damages as a result, the Commercial Contributor 
must pay those damages. 


B.5. No Warranty 


EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, THE PROGRAM IS PROVIDED 
ON AN "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, EITHER 
EXPRESS OR IMPLIED INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OR 
CONDITIONS OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A 
PARTICULAR PURPOSE. Each Recipient is solely responsible for determining the appropriateness of 
using and distributing the Program and assumes all risks associated with its exercise of rights under this 
Agreement, including but not limited to the risks and costs of program errors, compliance with applicable 
laws, damage to or loss of data, programs or equipment, and unavailability or interruption of operations. 


B.6. Disclaimer of Liability 


EXCEPT AS EXPRESSLY SET FORTH IN THIS AGREEMENT, NEITHER RECIPIENT NOR ANY 
CONTRIBUTORS SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, 
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT 
LIMITATION LOST PROFITS), HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE 
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PROGRAM OR THE EXERCISE OF ANY RIGHTS GRANTED HEREUNDER, EVEN IF ADVISED 
OF THE POSSIBILITY OF SUCH DAMAGES. 


B.7. General 


If any provision of this Agreement is invalid or unenforceable under applicable law, it shall not affect the 
validity or enforceability of the remainder of the terms of this Agreement, and without further action by 
the parties hereto, such provision shall be reformed to the minimum extent necessary to make such 
provision valid and enforceable. 


If Recipient institutes patent litigation against a Contributor with respect to a patent applicable to 
software (including a cross-claim or counterclaim in a lawsuit), then any patent licenses granted by that 
Contributor to such Recipient under this Agreement shall terminate as of the date such litigation is filed. 
In addition, if Recipient institutes patent litigation against any entity (including a cross-claim or 
counterclaim in a lawsuit) alleging that the Program itself (excluding combinations of the Program with 
other software or hardware) infringes such Recipient’s patent(s), then such Recipient’s rights granted 
under Section 2(b) shall terminate as of the date such litigation is filed. 


All Recipient’s rights under this Agreement shall terminate if it fails to comply with any of the material 
terms or conditions of this Agreement and does not cure such failure in a reasonable period of time after 
becoming aware of such noncompliance. If all Recipient’s rights under this Agreement terminate, 
Recipient agrees to cease use and distribution of the Program as soon as reasonably practicable. 
However, Recipient’s obligations under this Agreement and any licenses granted by Recipient relating to 
the Program shall continue and survive. 


Everyone is permitted to copy and distribute copies of this Agreement, but in order to avoid inconsistency 
the Agreement is copyrighted and may only be modified in the following manner. The Agreement 
Steward reserves the right to publish new versions (including revisions) of this Agreement from time to 
time. No one other than the Agreement Steward has the right to modify this Agreement. IBM is the 
initial Agreement Steward. IBM may assign the responsibility to serve as the Agreement Steward to a 
suitable separate entity. Each new version of the Agreement will be given a distinguishing version 
number. The Program (including Contributions) may always be distributed subject to the version of the 
Agreement under which it was received. In addition, after a new version of the Agreement is published, 
Contributor may elect to distribute the Program (including its Contributions) under the new version. 
Except as expressly stated in Sections 2(a) and 2(b) above, Recipient receives no rights or licenses to the 
intellectual property of any Contributor under this Agreement, whether expressly, by implication, 
estoppel or otherwise. All rights in the Program not expressly granted under this Agreement are reserved. 


This Agreement is governed by the laws of the State of New York and the intellectual property laws of 
the United States of America. No party to this Agreement will bring a legal action under this Agreement 
more than one year after the cause of action arose. Each party waives its rights to a jury trial in any 
resulting litigation. 
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.SystemErrorCode, 401 


AbsRect2LogRect, 232 
Add 
ComboBox class, 576 
ImageList class, 763 
ListBox class, 586 
ListControl class, 641 
TreeControl class, 676 
Add button control methods, 284 
Add static control methods, 315 
Add... methods, 281 
AddAttribute, 113 
AddAutoStartMethod, 189 
addBitmapButton, 288 
addBlackFrame, 334 
addBlackRect, 333 
addButton, 285 
addButtonGroup, 291 
AddCategoryComboEntry, 393 
AddCategoryListEntry, 395 
addCheckBox, 305 
addCheckBoxStem, 311 
addCheckGroup, 308 
addComboBox, 349 
AddComboEntry, 126 
addCombolInput, 358 
AddDirectory 
ComboBox class, 581 
ListBox class, 595 
addEntryLine, 340 
addEtchedFrame, 335 
addEtchedHorizontal, 337 
addEtched Vertical, 338 
AddExtendedStyle, 610 
AddFullSeq, 732 
addGrayFrame, 331 
addGrayRect, 330 
addGroupBox, 284 
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addIcon, 339 

ImageList class, 766 
addImage, 325 
addImages 

ImageList class, 767 
addInput, 351 
addInputGroup, 354 
addInputStem, 360 
AddLine 

InputBox class, 34 

PasswordBox class, 35 
addListBox, 347 
AddListControl, 495 
AddListEntry, 134 
addMasked 

ImageList class, 764 
AddMenultem, 367 
AddMenuSeparator, 368 
addOkCancelLeftBottom, 295 
addOkCancelLeftTop, 296 
addOkCancelRightBottom, 294 
addOkCancelRightTop, 295 
addPasswordLine, 344 
AddPopupMenu, 367 
addProgressBar, 499 
addRadioButton, 296 
addRadioGroup, 299 
addRadioStem, 302 
addRow, 642 
addScrollBar, 364 
AddSequence, 732 
AddSliderControl, 500 
addStatic, 316 
AddStyle 

EditControl class, 568 

ListControl class, 609 
AddTabControl, 503 
addText, 320 
AddTreeControl, 493 
addUserMsg, 107 
addWhiteFrame, 329 
addWhiteRect, 327 
AdjustToRectangle, 742 
AdvancedControls class, 477 
AlignLeft, 664 
AlignTop, 665 
animated button methods, 189 
AnimatedButton class, 544 


appearance methods 
BaseDialog class, 151 

Arrange, 664 

AskDialog, 44 

AssignFocus, 214 

AsyncMessageHandling, 81 

AutoDetection, 74 


B 

DlgArea class, 424 
BackgroundBitmap, 181 
BackgroundColor, 153 

ProgressBar class, 726 
barColor 

ProgressBar class, 725 
BaseDialog attributes, 68 
BaseDialog class, 57 
bitmap methods, 178, 241 
BkColor, 669 
BkColor=, 669 
Bottom 

DlgArea class, 424 

Rect class, 415 
bottom= 

Rect class, 415 
Button Controls, 513 
ButtonControl class, 513 


Cancel, 125 

CaptureMouse, 240 
CategoryComboAddDirectory, 395 
CategoryComboDrop, 395 
CategoryDialog class, 377 
CategoryListAddDirectory, 397 
CategoryListDrop, 397 
CategoryPage, 384 

Center, 169 

ChangeBitmap, 529 
ChangeBitmapButton, 178 
ChangeCategoryComboEntry, 395 
ChangeCategoryListEntry, 397 
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ChangeComboEntry, 131 
ChangeListEntry, 139 
ChangePage, 386 
check, 539 

ListControl class, 621 
CheckAll, 623 
CheckBox class, 540 
checked, 538, 541 
checkInGroup, 537 
CheckList 

class, 39 

function, 51 
CheckMenultem, 193 
Child, 685 
class methods 

BaseDialog class, 66 
Clear, 228 
ClearButtonRect, 177 
ClearMessages, 82 
ClearRect 

BaseDialog class, 176 

DialogControl class, 228 
ClearSelRange, 717 
ClearTicks, 710 
ClearWindowRect, 177 
click 

ButtonControl class, 516 
ClientToScreen, 233 
CloseDropDown, 582 
Collapse, 689 
CollapseAndReset, 690 
colorRef, 754 
ColumnInfo, 629 
ColumnWidth, 630 
Column Width=, 597 
CombineELwithSB, 143 
combo box methods, 126, 393 
ComboAddDirectory, 131 
ComboBox class, 575 
ComboDrop, 133 
comCtl32 Version, 404 
Common Public License, 789 
connect attribute methods 

BaseDialog class, 109 
connect event methods 

BaseDialog class, 83 

DialogControl class, 219 
Connect... methods, 387 
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ConnectAIISBEvents, 106 
ConnectAnimatedButton, 189 
ConnectBitmapButton, 99 
ConnectButton, 98 
connectButtonNotify, 458 
ConnectCheckBox, 111 
connectComboBox, 110 
ConnectComboBoxNotify, 467 
ConnectCommonNotify, 441 
ConnectControl, 101 
ConnectDraw, 102 
ConnectEditNotify, 462 
ConnectEntryLine, 109 
ConnectFKeyPress 
BaseDialog class, 94 
DialogControl class, 223 
ConnectHelp, 87 
ConnectKeyPress 
BaseDialog class, 89 
DialogControl class, 219 
ConnectList, 103 
ConnectListBox, 112 
ConnectListBoxNotify, 465 
ConnectListControl, 492 
ConnectListLeftDoubleClick, 103 
ConnectListNotify, 448 
ConnectListViewNotify, 453 
ConnectMenultem, 191 
ConnectMouseCapture, 87 
ConnectMove, 85 
ConnectMultiListBox, 112 
ConnectPosChanged, 86 
ConnectRadioButton, 111 
ConnectResize, 83 
ConnectScrollBar, 104 
ConnectScrollBarNotify, 469 
ConnectSliderControl, 492 
ConnectSliderNotify, 473 
connectStaticNotify, 460 
ConnectTabControl, 492 
ConnectTabNotify, 471 
ConnectTreeControl, 491 
ConnectTreeNotify, 443 
conversion methods, 231 
CorrectionFactor 
DlgAreaU class, 431 
CountTicks, 711 
CPL, 789 
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Create, 275 

ImageList class, 762 
CreateBrush, 261 
CreateCategoryDialog, 384 
CreateCenter, 277 
createFont, 252 
createFontEx, 253 
CreateMenu, 366 
CreatePen, 262 
CurrentCategory, 385 
CursorPos, 236 
Cursor_AppStarting, 238 
Cursor_Arrow, 238 
Cursor_Cross, 238 
Cursor_No, 239 
Cursor_Wait, 239 
CX 

DlgArea class, 424 
CY 

DlgArea class, 424 


debugging methods, 195 
Define 
TimedMessage, 32 
DefineDialog 
CategoryDialog class, 383 
InputBox class, 34 
UserDialog class, 278 
DefListDragHandler, 451 
DefTreeDragHandler, 446 
Delnstall, 126 
Delete 
ComboBox class, 577 
ListBox class, 587 
ListControl class, 643 
TabControl class, 735 
TreeControl class, 688 
DeleteAll 
ComboBox class, 577 
ListBox class, 587 
ListControl class, 644 
TabControl class, 735 
TreeControl class, 689 
DeleteCategoryComboEntry, 393 
DeleteCategoryListEntry, 396 


DeleteColumn, 627 
DeleteComboEntry, 128 
deleteFont, 260 
DeleteListEntry, 135 
DeleteObject, 264 
deprecated 
BaseDialog class 
assignWindow, 170 
getSystemMetrics, 150 
extenal functions 
errorMessage, 54 
getFileNameWindow, 56 
getScreenSize, 55 
getSysMetrics, 55 
infoMessage, 54 
playSoundFile, 55 
playSoundFileInLoop, 55 
sleepMS, 56 
stopSoundFile, 55 
winTimer, 56 
yesNoMessage, 54 
external functions, 53 
ListControl class 
removelmages, 662 
removeSmallImages, 661 
setImages, 661 
setSmallImages, 661 
PlainBaseDialog class 
getTextSize, 188 
public routines 
systemMetrics, 48 
RadioButton class 
indeterminate, 540 
isChecked, 539 
TabControl class 
removelmages, 740 
setImages, 740 
TreeControl class 
removelmages, 700 
setImages, 700 
Deselect, 649 
DeselectIndex, 589 
DeselectRange, 591 
DeterminePosition, 601 
DetermineSBPosition, 144 
device context methods 
BaseDialog class, 183 
DialogControl class, 242 
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dialog control methods, 365 
DialogControl class, 197 
DimBitmap, 535 
Disable, 203 
disable methods 
BaseDialog class, 151 
CategoryDialog class, 398 
DialogControl class, 200 
DisableCategoryItem, 398 
DisableItem, 163 
DisableMenultem, 192 
DisconnectKeyPress 
BaseDialog class, 95 
DialogControl class, 225 
DisplaceBitmap 
BaseDialog class, 182 
ButtonControl class, 531 
Display, 202 
DlgArea class, 422 
DlgAreaU class, 430 
DIgUtil class, 402 
Draw, 228 
draw methods 
BaseDialog class, 174 
DialogControl class, 227 
DrawAngleArc, 270 
DrawArc, 267 
DrawBitmap 
BaseDialog class, 179 
ButtonControl class, 534 
DrawButton, 174 
DrawLine, 265 
DrawPie, 268 
DrawPixel, 266 
DropHighlight, 697 
DropHighlighted 
ListControl class, 651 
TreeControl class, 686 
Dump, 195 
duplicate 
ImageList class, 770 
Dynamically Resizable dialogs 
DlgAreaU class, 432 
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Edit 
ListControl class, 667 
TreeControl class, 694 
EditControl class, 549 
EditSelection, 583 
Enable, 203 
enable methods 
BaseDialog class, 151 
CategoryDialog class, 398 
DialogControl class, 200 
EnableCategoryItem, 398 
Enableltem, 163 
EnableMenultem, 192 
EndAsyncExecution, 78 
EndEdit 
ListControl class, 667 
TreeControl class, 694 
EnsureCaret Visibility, 553 
Ensure Visible 
BaseDialog class, 155 
ListControl class, 656 
TreeControl class, 692 
ErrorDialog, 44 
Execute 
BaseDialog class, 75 
InputBox class, 35 
TimedMessage class, 33 
ExecuteAsync, 76 
Expand, 691 


FilenameDialog, 45 
File Viewer.rex 
example code, 171 
FillDrawing, 269 
Find 
ComboBox class, 578 
ListBox class, 587 
ListControl class, 662 
FindCategoryComboEntry, 394 
FindCategoryListEntry, 396 
FindComboEntry, 128 
FindListEntry, 136 
FindNearestX Y, 663 


ooRexx OODialog Reference Version 4.0.0 797 


FindPartial, 662 
FindWindow, 47 
FirstVisible 

ListControl class, 651 

TreeControl class, 686 
First VisibleLine, 553 
Focus 

ListControl class, 651 

TabControl class, 737 
FocusCategoryItem, 399 
Focused 

ListControl class, 650 

TabControl class, 738 
FocusItem, 159 
FontColor, 261 
fontName 

PlainBaseDialog class, 68 
fontSize 

PlainBaseDialog class, 71 
FontToDC, 260 
Foreground Window, 209 
FreeButtonDC, 184 
FreeDC, 243 
FreeWindowDC, 183 
fromFiles 

Image class, 752 
fromIDs 

Image class, 753 


future directions, 14 


Get, 146 
get and set methods 
BaseDialog class, 114 
get methods 
CategoryDialog class, 389 
GetArcDirection, 268 
GetAttrib, 122 
GetBitmapSizeX 
BaseDialog class, 179 
ButtonControl class, 534 
GetBitmapSizeY 
BaseDialog class, 179 
ButtonControl class, 534 
GetBmpDisplacement 
BaseDialog class, 182 


ButtonControl class, 531 
GetButtonControl, 479 
GetButtonDC, 183 
GetButtonRect, 150 
GetCategoryAttrib, 392 
GetCategoryCheckBox, 391 
GetCategoryComboEntry, 394 
GetCategoryComboltems, 394 
GetCategoryComboLine, 391 
GetCategoryEntryLine, 389 
GetCategoryListEntry, 396 
GetCategoryListItems, 396 
GetCategoryListLine, 390 
GetCategoryListWidth, 390 
GetCategoryMultiList, 390 
GetCategoryRadioButton, 391 
GetCategory Value, 392 
Getcheck, 624 
GetCheckBox, 121 
GetCheckControl, 481 
getCheckState 

CheckBox class, 541 

RadioButton class, 538 
GetClientRect, 213 
getColumnCount 

ListControl class, 632 
getColumnOrder 

ListControl class, 632 
GetComboBox, 484 
GetComboEntry, 129 
GetComboltems, 129 
GetComboLine, 119 
GetControlID, 147 
getCount 

ImageList class, 769 
GetCurrentCategoryCombolIndex, 394 
GetCurrentCategoryListIndex, 396 
GetCurrentCombolIndex, 129 
GetCurrentListIndex, 138 
GetData, 114 
GetDataStem, 124 
GetDC, 242 
GetEditControl, 479 
GetEntryLine, 116 
getExStyleRaw, 211 
GetExtendedStyle, 616 
GetExtendedStyleRaw, 618 
GetFirstVisible, 593 
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GetFocus, 214 
getFont, 251 
getFontName 
PlainBaseDialog class, 67 
getFontSize 
PlainBaseDialog class, 68 
getGroupBox, 482 
GetHoverTime, 619 
getIcon 
StaticControl class, 510 
GetID, 209 
getIdealSize, 522 
getImage 
ButtonControl class, 528 
Image class, 750 
ResourcelImage class, 778 
StaticControl class, 512 
getImageList 
ButtonControl class, 524 
ListControl class, 660 
TabControl class, 739 
TreeControl class, 699 
getImages 
Resourcelmage class, 779 
getImageSize 
ImageList class, 769 
Сешеш, 147 
GetLine, 557 
GetLineStep, 713 
GetListBox, 483 
GetListControl, 487 
GetListEntry, 136 
GetListItemHeight, 137 
GetListItems, 137 
GetListLine, 117 
GetListWidth, 133 
GetMenultemState, 194 
GetMouseCapture, 239 
GetMultiList, 118 
GetPageStep, 713 
GetPixel, 266 
GetPos 
BaseDialog class, 149 
DialogControl class, 149 
ProgressBar class, 721 
getProgressBar, 488 
GetRadioButton, 120 
GetRadioControl, 480 
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getRange 

ProgressBar class, 723 
GetRect, 211 
getRValue, 755, 756, 757 
GetSBPos, 142 
GetSBRange, 141 
GetScrollBar, 485 
GetSelectedPage, 385 
GetSelf, 145 
GetSize, 214 
GetSliderControl, 489 
GetStaticControl, 478 
GetStyle 

EditControl class, 572 
getStyleRaw, 209 
getSystemMetrics 

DIgUtil class, 409 
GetTabControl, 490 
GetText, 558 

ComboBox class, 580 

ListBox class, 593 

StaticControl class, 509 
getTextMargin, 523 
getTextSizeDlg 

PlainBaseDialog class, 151 
getTextSizeScreen, 240 
GetTick, 711 
GetTreeControl, 486 
GetValue, 121 
GetWindowDC, 183 
GetWindowRect, 150 
graphic drawing methods, 264 
graphic methods, 261 
GrayMenultem, 193 
GroupBox class, 542 


H 
DlgArea class, 425 
handle 
Image class, 757 
ImageList class, 774 
Resourcelmage class, 783 
HandleMessages, 81 
HasKeyPressConnection 


BaseDialog class, 97 
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DialogControl class, 226 
height 

Size class, 421 
height= 

Size class, 421 
Help, 125 
Hide 

DialogControl class, 201 
hide methods 

BaseDialog class, 151 

CategoryDialog class, 398 

DialogControl class, 200 
HideCategoryItem, 398 
HideFast, 201 
HidelItem, 163 
HideltemFast, 164 
HideWindow, 165 
HideWindowFast, 165 
HitTest, 700 
hiWord, 406 
HR 

DlgArea class, 425 
HScrollPos, 234 


id 
Image class, 749 

Image class, 747 

ImageList class, 761 

Indent, 693 

Indent=, 693 

InfoDialog, 44 

Init 
CategoryDialog class, 379 
CheckList class, 40 
DlgArea class, 423 
DlgAreaU class, 430 
InputBox class, 33 
ListChoice class, 38 
MultiInputBox class, 36 
RcDialog class, 374 
SingleList class, 41 
TimedMessage class, 31 
UserDialog class, 274 

InitAutoDetection 


BaseDialog class, 74 


UserDialog class, 275 
InitCategories, 381 
InitDialog 

BaseDialog class, 74 

CategoryDialog class, 384 
InitRange, 707 
InitSelRange, 715 
InputBox 

class, 33 

function, 50 
Insert 

ComboBox class, 576 

ListBox class, 586 

ListControl class, 636 

TabControl class, 730 

TreeControl class, 674 
InsertCategoryComboEntry, 393 
InsertCategoryListEntry, 395 
InsertColumn, 626 
InsertComboEntry, 127 
InsertListEntry, 135 
IntegerBox 

class, 35 

function, 50 
IsAncestor, 703 
IsChecked 

ListControl class, 625 
IsDialogActive, 80 
IsDropDownOpen, 582 
isEnabled, 204 
IsMaximized, 159 
IsMinimized, 158 
IsModified, 553 
IsMouseButtonDown, 240 
isNull 

Image class, 759 

ImageList class, 774 

Resourcelmage class, 784 
isVisible, 203 
ItemHeight, 597 
ItemHeight=, 597 
ItemInfo 

ListControl class, 646 

TabControl class, 734 

TreeControl class, 681 
ItemPos, 665 
Items 

ComboBox class, 580 
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ListBox class, 591 
ListControl class, 645 
TabControl class, 733 
TreeControl class, 683 
ItemsPerPage, 668 
ItemState, 648 
ItemText, 647 
ItemTitle, 116 


KeyName, 435 


L 

DlgArea class, 425 
Last 

ListControl class, 645 

TabControl class, 736 
LastError 

DlgAreaU class, 431 
LastSelected, 650 
Leaving, 126 
Left 

DlgArea class, 425 

Rect class, 412 
left= 

Rect class, 413 
License, Common Public, 789 
License, Open Object Rexx, 789 
LineFromIndex, 556 
LineIndex, 555 
LineLength, 556 
Lines, 554 
LineScroll, 552 
list box methods, 133, 395 
ListAddDirectory, 140 
ListBox class, 585 
ListChoice 

class, 37 

function, 51 
ListControl class, 603 
ListDrop, 140 
Load, 278 
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LoadBitmap, 241 
LoadFrame, 279 
LoadItems, 280 
LoadMenu, 368 
LogRect2AbsRect, 231 
loWord, 405 


MakeFirst Visible 
ListBox class, 592 
TreeControl class, 696 

Margim 

DlgArea class, 425 

Margins, 562 

Maximize, 156 

Menu methods, 366 

BaseDialog class, 191 





MessageExtensions class, 441 
methods for dialog items, 388 
methods for handles, sizes, and positions, 145 
methods to query OS values, 145 
Minimize, 155 
miscellaneous dialog control methods, 218 
modification messages 
ListControl class, 671 
Modify 
ComboBox class, 580 
ListBox class, 594 
ListControl class, 637 
TabControl class, 731 
TreeControl class, 679 
ModifyColumn, 628 
mouse and cursor methods, 236 
Move, 207 
MoveCategoryltem, 399 
Moveltem 
BaseDialog class, 169 
TreeControl class, 702 
MSSleep, 48 
MultiInputBox 
class, 36 
function, 50 
MultiListChoice 
class, 39 


function, 51 
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new 
Image class, 749 
ImageList class, 762 
Point class, 416 
Rect class, 411 
ResDialog class, 371 
ResoucelImage class, 776 
Size class, 419 
StaticControl class, 508 
Next 
ListControl class, 652 
TreeControl class, 686 
NextLeft, 653 
NextPage, 386 
NextRight, 654 
NextSelected, 652 
NextVisible, 687 
NoAutoDetection, 74 
NoMove 
DlgAreaU class, 431 
NoResize 
DlgAreaU class, 432 
Notices, 787 








notification messages 


TreeControl class, 703 


ObjectToDC, 263 

OK, 124 

ooDialog public routines, 43 
ooRexx License, 789 


OpaqueText, 246 


Open Object Rexx License, 789 


OpenDropDown, 582 
or 
DlgUtil class, 407, 408 


overview, 5 


PageHasChanged, 386 
Parent, 684 
PasswordBox 
class, 35 
function, 50 
PasswordChar, 561 
PasswordChar=, 560 
PeekDialogMessage, 82 
PlainBaseDialog class, 17 
PlainUserDialog, 17 
PlainUserDialog Attributes, 18 
PlainUserDialog class, 17 
PlainUserDialog Methods, 19 
Play, 43 
Point class, 415 
Popup, 78 
PopupAsChild, 79 
Pos, 707 
Pos=, 706 
Position, 601 
PosRectangle, 741 
Prepare4nItems, 645 
preparing and running dialogs, 72 
Previous 
ListControl class, 653 
TreeControl class, 687 
PreviousPage, 386 
PreviousSelected, 652 
Previous Visible, 688 
ProcessMessage, 218 
ProgressBar class, 719 
PropertySheet class, 745 
public routines 
AskDialog, 44 
CheckList, 51 
ErrorDialog, 44 
FileNameDialog, 45 
FindWindow, 47 
InfoDialog, 44 
InputBox, 50 
IntegerBox, 50 
ListChoice, 51 
MSSleep, 48 
MultülInputBox, 50 
MultiListChoice, 51 
PasswordBox, 50 
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Play, 43 
ScreenSize, 48 
SingleSelection, 53 
TimedMessage, 49 

push 
ButtonControl class, 515 


R 

DlgArea class, 426 
RadioButton class, 536 
Range 

ScrollBar class, 600 

SliderControl class, 710 
RcDialog class, 373 
Rect class, 410 
Rectangle, 264 
Redraw, 229 
RedrawButton, 175 
RedrawClient, 230 
RedrawlItems, 655 
RedrawRect 

BaseDialog class, 174 

DialogControl class, 229 
RedrawWindow, 167 
RedrawWindowRect, 176 
release 

Image class, 758 

ImageList class, 773 

ResourcelImage class, 782 
ReleaseMouseCapture, 240 
remove 

ImageList class, 771 
removeAll 

ImageList class, 772 
RemoveBitmap, 242 
RemoveExtendedStyle, 614 
RemoveStyle 

EditControl class, 570 

ListControl class, 609 
ReplaceExtendedStyle, 615 
ReplaceSelText, 560 
ReplaceStyle 

EditControl class, 571 

ListControl class, 607 
RequiredWindowSize, 743 
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ResDialog class, 371 
Resize, 206 
ResizeCategoryItem, 399 
Resizeltem, 168 
Resource file dialogs, 371 
RcDialog class, 373 
ResDialog class, 371 
ResourcelImage class, 775 
Resources, 747 
Restore, 157 
RestoreCursorShape, 237 
RestoreEditClass 
ListControl class, 667 
TreeControl class, 695 
Right 
DlgArea class, 426 
Rect class, 414 
right= 
Rect class, 414 
Root, 684 
Rows, 734 
Run, 75 


ScreenSize, 48 
ScreenToClient, 232 
Scroll 
ButtonControl class, 532 
DialogControl class, 233 
ListControl class, 668 
scroll bar methods, 141 
scroll methods, 233 
ScrollBar class, 599 
ScrollBitmapFromTo 
BaseDialog class, 180 
ButtonControl class, 536 
ScrollButton, 187 
ScrollCommand, 551 
ScrollInButton, 186 
ScrollText 
BaseDialog class, 185 
ButtonControl class, 532 
Select 
ComboBox class, 579 
EditControl class, 550 
ListBox class, 589 
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ListControl class, 649 
TabControl class, 736 
TreeControl class, 695 
Selected 
ComboBox class, 578 
EditControl class, 550 
ListBox class, 588 
ListControl class, 650 
TabControl class, 736 
TreeControl class, 685 
SelectedIndex 
ComboBox class, 578 
ListBox class, 588 
TabControl class, 736 
SelectedIndexes, 592 
SelectedItems 
ListBox class, 592 
ListControl class, 646 
SelectIndex 
ComboBox class, 579 
ListBox class, 589 
TabControl class, 737 
SelectRange, 590 
SelRange, 718 


SendMessageToCategoryltem, 399 


SendMessageToltem, 82 
set methods 

CategoryDialog class, 389 
SetArcDirection, 268 
SetAttrib, 123 
SetCategoryAttrib, 392 
SetCategoryCheckBox, 392 
SetCategoryComboLine, 391 
SetCategoryEntryLine, 389 
SetCategoryItemFont, 398 
SetCategoryListLine, 390 
SetCategoryListTabulators, 397 
SetCategoryListWidth, 390 
SetCategoryMultiList, 391 
SetCategoryRadioButton, 391 
SetCategoryStaticText, 389 
SetCategory Value, 392 
SetCheckBox, 121 
SetColor, 216 
setColumnOrder 

ListControl class, 634 
SetColumn Width, 631 
SetComboLine, 119 


SetCurrentCategoryCombolIndex, 394 
SetCurrentCategoryListIndex, 397 
SetCurrentCombolIndex, 130 
SetCurrentListIndex, 138 
SetCursorPos, 236 
SetData, 115 
SetDataStem, 123 
setDefaultFont 
PlainBaseDialog class, 66 
SetEntryLine, 117 
SetFocus, 214 
SetFocusToWindow, 215 
setFont, 251 
SetForegroundWindow, 208 
SetGroup, 161, 204 
SetHoverTime, 620 
SetHScrollPos, 235 
зейсоп 
StaticControl class, 509 
setImage 
ButtonControl class, 529 
StaticControl class, 511 
setImageList, 526 
ListControl class, 657 
TabControl class, 738 
TreeControl class, 698 
setIndeterminate, 542 
SetItemFont, 187 
SetItemPos, 666 
SetItemState, 639 
setItemText, 638 
SetLimit, 560 
SetLineStep, 714 
SetListColumnWidth, 134 
SetListItemHeight, 138 
SetListLine, 118 
SetListTabulators, 139 
SetListWidth, 133 
SetMargins, 562 
setMarquee 
ProgressBar class, 724 
SetMax, 709 
SetMenu 
ResDialog class, 373 
UserDialog class, 368 
SetMenultemRadio, 194 
SetMin, 708 
SetModified, 554 
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SetMultiList, 119 
SetPadding, 740 
SetPageStep, 714 
setPos 
ProgressBar class, 720 
ScrollBar class, 600 
SliderControl class, 706 
SetRadioButton, 120 
setRange 
ProgressBar class, 722 
ScrollBar class, 599 
SetReadOnly, 561 
SetRect, 212 
SetSBPos, 142 
SetSBRange, 141 
SetSelEnd, 717 
SetSelStart, 716 
SetSize, 741 
SetStaticText, 116 
setStep, 722 
SetTabStop, 162 
SetTabulators, 594 
SetText, 558 
StaticControl class, 508 
setTextMargin 
ButtonControl class, 523 
SetTickAt, 712 
SetTickFrequency, 712 
Setting up the dialog, 379 
SetTitle, 217 
SetValue, 122 
SetVScrollPos, 235 
SetWidth, 596 
SetWindowRect, 166 
SetWindowTitle, 170 
Show 
BaseDialog class, 153 
DialogControl class, 201 
show methods 
BaseDialog class, 151 
CategoryDialog class, 398 
DialogControl class, 200 
ShowBalloon, 563, 564, 567 
ShowCategoryltem, 398 
ShowFast, 201 
Showltem, 164 
ShowlItemFast, 164 
ShowWindow, 165 
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Show WindowFast, 166 
SingleSelection 
class, 41 
function, 53 
Size class, 419 
SliderControl class, 705 
SmallSpacing, 654 
SnapToGrid, 664 
SortChildren, 697 
Spacing, 654 
standard dialogs, 30 
CheckList, 39 
InputBox, 33 
IntegerBox, 35 
ListChoice, 37 
MultüInputBox, 36 
MultiListChoice, 39 
PasswordBox, 35 
SingleSelection, 41 
TimedMessage, 30 
Standard Dialogs, Public Routines, 29 
standard event methods, 124 
StartIt 
CategoryDialog class, 387 
ResDialog class, 372 
UserDialog class, 365 
state, 516 
state=, 517 
StaticControl class, 507 
step, 720 
Stoplt 
BaseDialog class, 81 
UserDialog class, 366 
StringWidth, 635 
style= 
ButtonControl class, 518 
GroupBox class, 543 
SubclassEdit 
ListControl class, 667 
TreeControl class, 695 
symbolic names for virtual keys, 436 
systemErrorCode 
Image class, 760 


ResourcelImage class, 785 
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DlgArea class, 426 
TabControl class, 729 
tabStop, 205 
TabToNext, 160 
TabToPrevious, 160 
text methods 

BaseDialog class, 184 

DialogControl class, 244 
TextBkColor, 670 
TextBkColor=, 670 
TextColor, 669 
TextColor=, 670 
TiledBackgroundBitmap, 181 
TimedMessage 

class, 30 

function, 49 
Title, 216 
Title=, 217 
Toggle, 692 
Top 

DigArea class, 426 

Rect class, 413 
top= 

Rect class, 413 
ToTheTop, 154 
TransparentText, 246 
TreeControl class, 673 


uncheck, 539 

ListControl class, 622 
UncheckAIl, 623 
UncheckMenultem, 193 
Update 

DialogControl class, 216 

ListControl class, 656 
UpdatelItem, 655 
UserDialog class, 271 
Utility Classes, 401 


Validate 
BaseDialog class, 126 


IntegerBox function, 36 


Value, 218 
Value=, 219 
VCode, 435 


version, 403 

view styles, 606 
VirtualKeyCodes class, 435 
VisibleItems, 683 
VScrollPos, 234 


WwW 

DlgArea class, 426 
Width 

ListBox class, 596 

Size class, 420 
width= 

Size class, 421 
WindowBase Class, 23 
WindowExtensions Class, 24 
WR 

DlgArea class, 427 
Write 

BaseDialog class, 184 

DialogControl class, 244 
WriteDirect, 245 
WriteToButton, 248 
WriteToWindow, 247 


X 
DlgArea class, 427 
Point class, 417 

х= 


Point class, 417 
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DlgArea class, 427 
Point class, 418 

y= 
Point class, 418 
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